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ABOUT THIS PUBLICATION 


VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). This publication describes how to install 
VS APL and how to perform various system management functions such as 
converting workspaces, defining VS APL users, and maintaining public and 
project libraries. It is intended for those who have responsibility for these 
functions. The reader is assumed to have knowledge of VS APL and 
Conversational Monitor System (CMS), which runs under VM/370, or 
Personal Computing (VSPC), which runs under OS/VS1 (Program Number 
5740-XR5), OS/VS2 (Program Number 5740-XR6), or DOS/VS (Program 
Number 5746-XR3). 


Unless noted otherwise, information in this publication about VS APL under 
VSPC applies to both OS/VS and DOS/VS. Information that pertains only to 
VS APL under DOS/VS (VSPC) will be provided for subsequent releases of 
VS APL. 


Major Divisions of the Publication 
“Introduction” describes the components of VS APL. 


“VS APL Distribution Volume” describes the contents and format of the VS 
APL distribution volume. 


“Installing VS APL under VM/370 (CMS)”’ explains how to install VS APL 
as a shared or non-shared system under VM/370 (CMS). 


“Installing VS APL under OS/VS (VSPC)” explains how to install VS APL 
as a foreground processor under OS/VS (VSPC). 


“Installing VS APL under DOS/VS (VSPC)”’ will, in a subsequent release, 
explain how to install VS APL as a foreground processor under DOS/VS 
(VSPC). | 


“Defining VS APL Users” explains how to define VS APL users to the host 
system. 


“Defining Auxiliary Processors” explains how to define auxiliary processors 
to the host system. 


“VS APL Public and Project Libraries” explains how to create and maintain 
VS APL public and project libraries. 


‘‘Workspace Conversion” explains how to convert APL \360, APLSV, and 
APL/CMS workspaces to VS APL workspaces for use under CMS or VSPC. 


‘Transporting Workspaces between CMS and VSPC”’ explains how to 
transport VS APL workspaces between CMS and VSPC. 


“Using the VS APL Microcode Assist’’ discusses the use of the VS APL 
microcode assist feature. 


“Storage Requirements” presents virtual storage and auxiliary storage 
requirements for VS APL. 


“Messages” contains information about error and diagnostic messages. 


‘Appendix A. VS APL Components” lists the items contained in each 
component of VS APL. 
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“Appendix B. Sample Terminal Session for VS APL under CMS” contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under CMS. 


“Appendix C. Sample Terminal Session for VS APL under VSPC”’ contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under OS/VS (VSPC) or DOS/VS (VSPC). 


Conventions Used in the Publication 


Required Publications 


The conventions used in describing the syntax of commands and statements 
are: 


¢ Expressions enclosed in brackets, [], are optional. 


« Items separated by an OR sign, |, are alternatives, only one of which may 
be specified. 


¢ Uppercase items must be entered as shown except that they may be 
truncated if so noted and, if entered at a terminal, they may be entered as 
either lowercase or uppercase. 


e Lowercase items are variables for which a value is substituted. 


e Parentheses, (), must be entered as shown. 


All readers must be familiar with some of the information presented in this 
publication: 


e VS APL General Information, GH20-9064, which provides a general 
description of VS APL. 


Readers concerned with VS APL under CMS must be familiar with some of 
the information presented in these publications: 


e IBM Virtual Machine Facility/370: Introduction, GC20-1800, which 
provides a general description of VM/370 and CMS. 


e IBM Virtual Machine Facility/370: Command Language Guide for 
General Users, GC20-1804, which provides basic information about CMS 
and CP for VM/370 Release 2. 


e IBM Virtual Machine Facility/370: Operator’s Guide, GC20-1806, 
which describes how to define VM/370 users and CMS virtual disks. 


e IBM Virtual Machine Facility/370: EDIT Guide, GC20-1805, which 
describes how to use the CMS editor for VM/370 Release 2. 


e VS APL for CMS: Terminal User’s Guide, SH20-9067, which 
describes how to use VS APL under CMS. 


e IBM Virtual Machine Facility/370: CMS User’s Guide, GC20-1819, 
which provides basic information about CMS and how to use the CMS 
editor to create and modify programs for VM/370 Release 3. 


e IBM Virtual Machine Facility/370: CP Command Reference for 
General Users, GC20-1820, which provides basic information about CP 
for VM/370 Release 3. 
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e IBM Virtual Machine Facility/370: Command and Macro Reference, 
GC20-1818, which provides reference material on CMS commands, 
subcommands, and macros for VM/370 Release 3. 


Readers concerned with VS APL under VSPC must be familiar with some of 
the information presented in these publications: 


« VS Personal Computing (VSPC) for OS/VS and DOS/VS: General 
Information, GH20-9070, which provides a general description of VSPC. 


« VS Personal Computing (VSPC) Installation Reference Material, 
SH20-9072, which describes the VSPC Service Program and the VSPC 
commands used in this publication. 


e VS APL for VSPC: Terminal User’s Guide, SH20-9066, which 
describes how to use VS APL under VSPC. 


Readers concerned with VS APL under OS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 


« OS/VS JCL Reference, GC28-0618, which describes the OS/VS JCL 
statements used in this publication. 


Readers concerned with VS APL under DOS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 


« DOS/VS System Control Statements, GC33-5376, which describes the 
DOS/VS control statements used in this publication. 


Related Publications 


Readers may need to be familiar with some of the information presented in 
these publications: 


¢ Operator’s Library: System/370 Model 135 Procedures, GC38-0005, 
which explains how to load the VS APL microcode assist feature on a 
System/370, Model 135. 


e IBM System/370 Model 145 Operating Procedures, GC38-0015, which 
explains how to load the VS APL microcode assist feature on a 
System/370, Model 145. 


e IBM Virtual Machine Facility/370: System Messages, GC20-1808, 
which lists CP and CMS messages. 


e OS/VS Message Library: VSPC Messages for VSI, GC38-1013, 
which lists OS/VS (VSPC) messages. 


« DOS/VS Messages, GC33-5379, which lists DOS/VS (VSPC) messages. 


e IBM Virtual Machine Facility/370: System Programmer’s Guide, 
GC20-1807, which describes shared systems. 


e IBM Virtual Machine Facility/370: Planning and System Generation 
Guide, GC20-1801, which describes how to implement a shared system. 
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INTRODUCTION 


VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). It runs under: 


e Conversational Monitor System (CMS), which runs under VM/370 


e Personal Computing (VSPC), which runs under OS/VS1, OS/VS2, and 
DOS/VS 


VS APL is divided into the six components described below. 


Interpreter: Scans, analyzes, and executes VS APL statements. It is fully 
independent of the environment in which VS APL operates. It is free of all 
dependencies on terminal type, library organization, host system, and other 
characteristics of a particular installation. 


Executor: Provides environment-dependent services for the interpreter, such 
as access to libraries and terminal input and output. There are two versions of 
the executor, one for use under CMS and one for use under VSPC. 


Shared Storage Manager: Enables programs that are operating concurrently 
to communicate with each other via shared variables. The shared storage 
manager distributed with VS APL is used only under CMS. Under VSPC, the 
shared storage manager is a component of VSPC. 


Auxiliary Processors: Provide services to VS APL users via shared variables. 
There are three internal auxiliary processors for use under VSPC; they are 
distributed as part of the executor. There are four auxiliary processors for use 
under CMS; they are distributed as a separate component. Also distributed 
with VS APL, for use under CMS only, is a set of macros that can be used to 
write auxiliary processors. Distributed with VSPC is a set of similar macros 
that comprise the VSPC background interface. 


Conversion Program: Converts APL\360, APLSV, and APL/CMS 
workspaces to VS APL workspaces. There are four versions of the conversion 
program, two for use under CMS, one for use under OS/VS, and one for use 
under DOS/VS. 


Distributed Workspaces: Provide useful functions for VS APL users. They are 
described in VS APL for CMS: Terminal User’s Guide and VS APL for 
VSPC: Terminal User’s Guide. 
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VS APL DISTRIBUTION VOLUME 


The VS APL distribution volume contains all the components of VS APL and 
the sample job control statements and procedures used to install it. For 
installation under VM/370 (CMS) and OS/VS (VSPC), the distribution 
volume is tape. For installation under DOS/VS (VSPC), the distribution 
volume is either tape or disk. The format of the distribution volume is shown 


in Figure 1. 

File File Characteristics 

Number Contents RECFM LRECL BLKSIZE 
1 All object code for DOS/VS (VSPC); FB 80 3440 


interpreter, executor (including internal 
auxiliary processors), and conversion 
program!. 


2 Sample job control statements to install F 80 80 
under DOS/VS and to run the conversion 
program!. 


3 Sample job control statements to install F 80 80 
under OS/VS and to run the conversion 
program. 


4 EXEC procedure to install under CMS; F 805 805 
in CMS TAPE DUMP format. 


5 Object code for the interpreter for CMS FB 80 3200 
and OS/VS (VSPC). 


6 Object code and other data for CMS; F 805 805 
executor, shared storage manager, 
auxiliary processors, conversion programs, 
and conversion procedures; in CMS TAPE 
DUMP format. 


7 Object code for OS/VS (VSPC); executor FB 80 3200 
(including internal auxiliary processors), 
and conversion program. 


8 Workspace 1 NEWS F 800 800 
9 Workspace 1 WSFNS F 800 800 
10 Workspace 1 CONVERT F 800 800 
11 Workspace 1 TYPEDRILL F 800 800 
12 Workspace 1 APLCOURSE F 800 800 
13 Workspace 1 PLOT F 800 800 
14 Workspace 1 EXAMPLES F 800 800 
15 Workspace 1 FORMAT F 800 800 
16 Workspace 2 VSFILES2 F 800 800 
17 Workspace 2 APFNS3 F 800 800 
18 Macros to write auxiliary processors for CMS FB 80 3200 


1 Files 1 and 2 are dummy files. Their contents will be as described above for subsequent releases of VS APL. 
2 Workspace VSFILES is used only under VSPC. 
3 Workspace APFNS is used only under CMS. 


Figure 1. Format of VS APL Distribution Volume 


VS APL Distribution Volume 13 


INSTALLING VS APL UNDER VM/370 (CMS) 


This section describes how to install VS APL as a shared or non-shared 
system under VM/370 (CMS). Installing VS APL as a shared system makes 
more efficient use of real storage and improves system performance. When 
VS APL is a shared system, all users share one copy of the VS APL executor, 
interpreter, and shared storage manager; an initialization routine (executor 
module APLSCINI) resides in each user’s virtual machine. When VS APL is a 
non-shared system, the VS APL executor, interpreter, and shared storage 
manager reside in each users’ virtual machine. Whether VS APL is shared or 
not, any auxiliary processors invoked by a user reside in his virtual machine. 


Before installing VS APL as a shared system, you should be familiar with the 
information about saved systems and shared segments presented in [BM 
Virtual Machine Facility/370: System Programmer’s Guide and IBM 
Virtual Machine Facility/370: Planning and System Generation Guide. 


Requirements for Installation 
The facilities required for installing VS APL under VM/370 (CMS) are: 
e« A System/370 machine configuration that can support VM/370 (CMS). 


- An installed release of VM/370 (CMS) of the required level or later: 
Release 3 (Program Level Change 1) if installing VS APL as a shared 
system; Release 2 (Program Level Change 13) if installing VS APL as a 
non-shared system. PTF number V02960 must be applied to CMS if it is 
not included in the release. The CP macro SYSTIME, which is used to 
define the VM/370 system timer, should have a ZONE option that 
correctly specifies the offset from Greenwich Mean Time. Otherwise, the 
value of the D7'S system variable and the time stamp printed in response 
to VS APL commands will be in Greenwich Mean Time. 


e A virtual machine large enough to install VS APL (see “‘Virtual Storage 
Requirements’’). 


e A magnetic tape device. 
e The VS APL distribution tape. 


« A CMS A-disk large enough to contain the VS APL distributed files (see 
*‘Auxiliary Storage Requirements’’). 


« A CMS Y-disk large enough to contain the generated VS APL system (see 
‘Auxiliary Storage Requirements’’). 


¢ If installing VS APL as a shared system, space on a CP-owned DASD 
volume for the system (see ‘‘Auxiliary Storage Requirements”’). 


e A terminal supported by CMS. 
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Overview of Installation Procedure 


In brief, the procedure for installing VS APL under VM/370 (CMS) is as 
follows. The procedure is described in detail in the next section. 


Installation Procedure 


NHN nn > W 


. Plan and define the CMS disks required for VS APL. 
. If installing VS APL as a shared system, plan the system’s load address and 


DASD space allocation. 


. Log on to VM/370 and IPL CMS. 
. Access and prepare the A-disk and the Y-disk. 
. Access the distribution tape. 


. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 


from the distribution tape to the A-disk. 


. Build VS APL by executing procedure APLINSTL. 
. If installing VS APL as a shared system, define, load, and save the system. 


. Test that VS APL is installed correctly by executing the sample terminal 


session (see Appendix B). 


. Plan the disk arrangement for the VS APL system, and define the disks as 


described in IBM Virtual Machine Facility/370: Operator’s Guide. Two 
disks are required: 


¢ One which is accessed as the A-disk during execution of the installation 
procedure. It will contain all the files transferred from the distribution 
tape and the module files created in step 7. The minimum space required 
is shown in “Auxiliary Storage Requirements.” Additional space should 
be allocated for future maintenance. At completion of the procedure, 
the A-disk should be kept as backup. 


e« One which is accessed as the Y-disk during execution of the installation 
procedure. It will contain the generated VS APL system. The minimum 
space required is shown in ‘“‘Auxiliary Storage Requirements.” 
Additional space should be allocated for public workspaces other than 
those distributed. The Y-disk will be accessed by VS APL users. It 
should be defined with a write password known only to those who are 
responsible for installing and maintaining VS APL. 


. If installing VS APL as a shared system, decide what the load address of 


the shared system will be. The address must be larger than the largest 
virtual machine of any VS APL user; the shared system must not overlay 
any other saved segment that will be attached at the same time as VS APL. 
The load address should not be unnecessarily high; if it is, real storage is 
wasted for unreferenced CP segment table entries. During step 7 of the 
installation procedure, enter the load address when prompted to do so. 


Also allocate permanent space on a CP-owned DASD volume to contain 


~ the saved system. For the space required, see “Auxiliary Storage 


Requirements.” 


. Log on to VM/370 and IPL CMS with a virtual machine large enough to 


install VS APL (see “Virtual Storage Requirements”’). 
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4. Access the A-disk and the Y-disk in read/write mode. If the disks are 
newly allocated, format them using the CMS FORMAT command. 


If the disks are not newly allocated, issue the CMS LISTFILE command, 
and check that no files with the identifications listed below exist. If there 
are any such files, rename them; otherwise they will be replaced in steps 6 
and 7. The files that are created on each disk are: 


Filename Filetype Disk 
APL EXEC A and Y 
APL MODULE A and Y 
APLCVCMS EXEC A and Y 
APLCVCMS MODULE A and Y 
APLCVRPQ EXEC A and Y 
APLCVRPQ MODULE A and Y 
APLIBTAB APLIBTAB A and Y 
APLMAC MACLIB A and Y 
APL100 TEXT A and Y 
APL101 TEXT A and Y 
APL110 TEXT A and Y 
APL111 TEXT A and Y 
APLMAIN MODULE Al 

APL MAP A 
APLCVCMS MAP A 
APLCVRPQ MAP A 
Filename Filetype Disk 
macro-name2 MACRO A 
APLINSTL EXEC A 
module-name?3 TEXT A 
APFNS W0000002 Y 
APLCOURS W0000001 Y 
CONVERT Wwo0000001 Y 
EXAMPLES W0000001 Y 
FORMAT W0000001 Y 
NEWS W0000001 Y 
PLOT W0000001 b 
TYPEDRIL W0000001 ng 
WSFNS W0000001 Y 


1 Created only when VS APL is installed as a shared system. 
2 There is a macro file for each macro listed in Appendix A under “Auxiliary Processor Macros.” 


3 There is a text file for each module listed in Appendix A under “CMS Executor Modules,” “Interpreter 
Modules,” “Shared Storage Manager Modules,” and “CMS Conversion Modules.” 


5. Ask the system operator to mount the distribution tape and to attach the 
tape drive as virtual device 181, 182, 183, or 184. 


6. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 
from the distribution tape to the A-disk by issuing these CMS commands: 


TAPE REW (address 
TAPE FSF 3 (address 
TAPE LOAD * * A (address 


address 
is the symbolic tape identification or the address of the device on which 
the distribution tape is mounted. 
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7. Invoke the procedure that builds VS APL by issuing this CMS command: 
APLINSTL 


The procedure is conversational; enter information when prompted to do 
so. The procedure performs the following actions: 


a. Transfers all required text and exec files (distribution tape nies 5 and 6) 
from the distribution tape to the A-disk. 


b. Transfers the distributed workspace files from the distribution tape to 
the Y-disk (workspace VSFILES, which is used only under VSPC, is not 
transferred). 


c. Transfers the auxiliary processor macros from the distribution tape to 
the A-disk and generates file APLMAC MACLIB. 


d. Copies the following files from the A-disk to the Y-disk: 
« APL EXEC (VS APL startup procedure) 


« APLCVCMS EXEC (APL\360 and APLSV conversion program 
procedure) 


° APLCVRPQ EXEC (APL/CMS conversion program procedure) 
« APLIBTAB APLIBTAB (library table file) 


e APL100 TEXT, APL101 TEXT, APL110 TEXT, and APL111 
TEXT (auxiliary processors) 


« APLMAC MACLIB (auxiliary processor macro library) 


e. Creates files APL MODULE (initialization routine for shared system; 
executor, interpreter, and shared storage manager for non-shared 
system), APLMAIN MODULE (executor, interpreter, and shared 
storage manager for shared system), APLCVCMS MODULE 
(APL\360 and APLSV conversion program), and APLCVRPQ 
MODULE (APL/CMS conversion program). 


f. Copies files APL MODULE, APLCVCMS MODULE, and 
APLCVRPO MODULE from the A-disk to the Y-disk. 


8. If installing VS APL as a shared system, define the system to CP and then 
load it and save it as follows: 


a. Define the system to be saved by adding a NAMESYS macro to your 
installation’s DMKSNT ASSEMBLE module. Code the macro as 
follows: 


APLMAIN NAMESYS SYSNAME=APLMAIN, 
SYSSIZE=172K, 
VSYSADR=IGNORE, 
SYSVOL=serial-number,! 
SYSSTRT=( cylinder, page ) ,2 
SYSPGCT=48, 
SYSPGNM=( 128-175) ,3 
SYSHRSG=(8,9,10 )3 

1 Provide the serial number of the volume on which space was allocated in step 2. 

2 Provide the starting cylinder and page address of the space allocated in step 2. 


3 The page and segment numbers shown are based on a load address of 512K. Provide the numbers 
that correspond to the load address you selected in step 2. 
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b. Assemble the new system name table (DMKSNT) by using the 
GENERATE EXEC procedure as described in [BM Virtual Machine 
Facility/370: Planning and System Generation Guide. 


c. Using a virtual machine large enough to contain the system to be saved 
(load address plus 400K), load the system and save it: 


LOADMOD APLMAIN 
SAVESYS APLMAIN 


d. Before continuing with step 9, log on to VM/370 with a smaller virtual 
machine (of a size no greater than the saved system’s load address). 


9. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix B). 


This completes the installation procedure. The A-disk should be kept for 
backup and maintenance of the system. The distributed workspaces must be 
kept on the Y-disk; that is, on the disk that is accessed as a Y-disk by VS 
APL users. The other files on the Y-disk (see list in step 4 above) can also be 
kept there or they can be transferred to the CMS system disk. 
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INSTALLING VS APL UNDER OS/VS (VSPC) 


This section describes how to install VS APL as a foreground processor under 
either OS/VS1 (VSPC) or OS/VS2 (VSPC). 


Requirements for Installation 
The facilities required for installing VS APL under OS/VS are: 


A System/370 machine configuration that can support OS/VS1 (VSPC) 
or OS/VS2 (VSPC). 


An installed release of OS/VS1 (VSPC) or OS/VS2 (VSPC). 


OS/VS Linkage Editor; utility programs IEBPTPCH, IEHPROGM, and 
IEBUPDTE; and job control program IEFBR14. 


A region large enough to run the VSPC Service Program and the OS/VS 
Linkage Editor. 


A magnetic tape device. 
The VS APL distribution tape. 


Space in OS/VS1 SYS1.LINKLIB or OS/VS2 SYS1.LPALIB for the VS 
APL load module (see “Auxiliary Storage Requirements’’). 


Space in OS/VS private libraries for the VS APL object decks and the 
conversion program load module (see “Auxiliary Storage Requirements’’). 


Space in VSPC public libraries for the distributed workspaces (see 
“Auxiliary Storage Requirements’’). 


Authorization to update OS/VS1 SYS1.LINKLIB or OS/VS2 
SYS1.LPALIB. 


Authorization as a VSPC chief administrator. 


A terminal supported by VSPC (required only to execute the sample 
terminal session). 


Overview of Installation Procedure 


In brief, the procedure for installing VS APL under OS/VS (VSPC) is as 
follows. The procedure is described in detail in the next section. 


I. 
2. 


Punch the sample JCL from the distribution tape. 


Allocate space for and catalog the data sets required for installing VS APL: 
VSAPL.OBJLIB and VSAPL.CNVTLIB. 


. Transfer object modules from the distribution tape to data set 


VSAPL.OBJLIB. 


. Link-edit the VS APL load module. 


5. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
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Installation Procedure 


6. Run the VSPC Service Program to define VS APL, public libraries 1 and 2, 


and the internal auxiliary processors to VSPC and to transfer the 
distributed workspaces to the VSPC libraries. 


7. Test that VS APL is installed correctly by executing the sample terminal 


session (see Appendix C). 


. Punch the OS/VS sample JCL procedures from the VS APL distribution 


tape by executing the following job: 


//PUNCHJCL JOB accounting-information,MSGLEVEL=1 
Ff. EXEC PGM=IEBPTPCH 
//SYSPRINT DD SYSOUT=A 
//SYSUT1 DD DSN=JCL, VOL=SER=APLDTR, UNIT=2400, 
df DISP=OLD, LABEL=(3,NL), 
S/ DCB=( LRECL=80 , BLKSIZE=80 , RECFM=F ) 
//SYSUT2 DD SYSOUT=B 
//SYSIN DD #* 

PUNCH 
/* 


There are six jobs in the sample JCL. The first five are used for each of the 


next five steps of the installation procedure. The last one is used to run the 
conversion program (see ““OS/VS Workspace Conversion Program’’). 


It may be necessary to alter the sample JCL to suit your requirements. In 
each step, the sample JCL is listed, and the modifications that may be 
required are noted. In this step and in steps 3 and 6, group name 2400 is 
used as the UNIT parameter to mean any magnetic tape device. In steps 4 
and 5, group name SYSDA is used as the UNIT parameter to mean any 
direct access device. If either of these names is not so defined for your 
installation, these parameters must be altered. 


. Allocate space for two partitioned data sets and catalog them: 


e VSAPL.OBJLIB, object module library for the executor, interpreter, 
and conversion program. 


e VSAPL.CNVTLIB, load module library for the conversion program. 
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Execution of job ALLOC from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 


/ /ALLOC JOB accounting-information,MSGLEVEL=1 


f/f EXEC PGM=IEFBR14 

//DD1 DD DSN=VSAPL.OBJLIB, DISP=(NEW,KEEP), 

// VOL=SER=volser,UNIT=typeunit, 

vad SPACE=( 3520,(130,5,20)), 

ff DCB=( LRECL=80 , BLKSIZE=3520 , RECFM=FB ) 
//DD2 DD DSN=VSAPL.CNVTLIB,DISP=(NEW,KEEP), 
Si VOL=SER=volser,UNIT=typeunit, 

// SPACE=(CYL,(1,1,1)) 

// EXEC PGM=IEHPROGM 


//SYSPRINT DD SYSOUT=A 
//SYSIN DD + 
CATLG DSNAME=VSAPL.OBJLIB, VOL=typeunit=volser 
CATLG DSNAME=VSAPL.CNVTLIB, VOL=typeunit=volser 
/* 


. Transfer files 5 and 7 from the VS APL distribution tape to data set 
VSAPL.OBJLIB. Execution of job BUILDOBJ from the sample JCL, 
altered to suit your requirements, accomplishes this step. Supply the 
information shown in lowercase below. 


Each input file is a series of object modules, each preceded by a ./ ADD 
NAME= statement. The BUILDOBJ job reads the two files and writes 
each object module as a member of VSAPL.OBJLIB. 


//BUILDOBJ JOB accounting-information,MSGLEVEL=1 
// EXEC PGM=IEBUPDTE , PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSN=VSAPL.OBJLIB,DISP=OLD 
//SYSIN DD DSN=INTERP.OBJECT, VOL=SER=APLDTR, 


// UNIT=2400,DISP=( OLD, PASS ), LABEL=(5,NL), 
Vea DCB=( LRECL=80 , BLKSIZE=3200 , RECFM=FB ) 
// EXEC PGM=IEBUPDTE, PARM=NEW 


//SYSPRINT DD SYSOUT=A 
J 7SYSUT2Z DD DSN=VSAPL.OBJLIB,DISP=OLD 
//SYSIN DD DSN=OSVS . DEPENDNT .OBJECT, VOL=SER=APLDTR, 


SH UNIT=2400,DISP=OLD, LABEL=(7,NL), 
// DCB=( LRECL=80 , BLKSIZE=3200 , RECFM=EFB ) 
/* 
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4. Link-edit the VS APL load module. Execution of job LINKAPL from the 
sample JCL, altered to suit your requirements, accomplishes this step. The 
job contains two SYSLMOD DD statements, one to link-edit VS APL into 
SYS1.LINKLIB for OS/VS1 and another to link-edit VS APL into 
SYS1.LPALIB for OS/VS2. Remove the statement that does not apply to 
your operating system, and supply the information shown in lowercase 
below. 


The link-edit map output from this step should be saved. 


//LGINKAPL JOB accounting-information,MSGLEVEL=1 
es EXEC PGM=HEWL, 
Jf PARM='RENT,NCAL, LIST,MAP, XREF' 
//SYSPRINT DD SYSOUT=A 
//OBJLIB DD DSN=VSAPL.OBJLIB, DISP=SHR 
//SYSLMOD DD , DSN=SYS1.LINKLIB,DISP=OLD (OS/VS1 ONLY ) 
//SYSLMOD DD DSN=SYS1.LPALIB,DISP=OLD (OS/VS2 ONLY ) 
//SYSUT1 DD UNIT=SYSDA,SPACE=( TRK, (40,10) ) 
//SYSLIN DD * 

INCLUDE OBJLIB(!) 


ENTRY APLPCOEX 

SETCODE AC(1 ) 

NAME APLPCOEX(R ) 
/* 


1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under “VSPC 
Executor Modules” and “Interpreter Modules.” , 


5. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
Execution of job LINKCNVT from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 


The link-edit map output from this step should be saved. 


//LINKCNVT JOB accounting-information,MSGLEVEL=1 
rea EXEC PGM=HEWL, PARM='NCAL,LIST,MAP,XREF,REUS' 
//SYSPRINT DD SYSOUT=A 
//OBJLIB DD DSN=VSAPL.OBJLIB,DISP=SHR 
//SYSLMOD DD DSN=VSAPL.CNVTLIB, DISP=OLD 
//SYSUT1 DD UNIT=SYSDA,SPACE=( TRK,( 40,10) ) 
//SYSLIN DD * 
INCLUDE OBJLIB(!) 


ENTRY COIBM 
NAME APLCVOS(R ) 
/* 


1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under 
“VSPC/OS Conversion Modules.” 
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6. Run the VSPC Service Program to: 


e Define VS APL as a foreground processor. 


¢ Define public libraries 1 and 2. 


¢ Define the distributed auxiliary processors. 


e Transfer the distributed workspaces from the distribution tape to 
libraries 1 and 2 (workspace APFNS, which is used only under CMS, is 
not transferred). . 


Execution of job VSPCSERV from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. Although files 8 through 16 of the distribution tape 
contain 800-byte unblocked records, they must be described as 80-byte 
blocked records to the IMPORT function of the VSPC Service Program. 
See VSPC Installation Reference Material for a description of the VSPC 
Service Program and control statements. 


//VSPCSERV 
// 
//SYSOLDIR 
//SYSOLIB1 
//SYSOLIB2 
//NEWS 

// 

he 

//WSENS 

// 

// 
//CONVERT 
// 

// 
//TYPEDRIL 
VE 

£/ 
//APLCOURS 
// 

it 

//PLOT 

// 

// 

/ /EXAMPLES 
fi 

// 

/ /EORMAT 
es 

// 
//NSEILES 
is. 

// 
//SYSPRINT 
//SYSIN 


JOB 
EXEC 


accounting-information,MSGLEVEL=1 
PGM=ASUSPEXC, PARM=NOLIST 
DSN=name , DISP=OLD 

DSN=name , DISP=OLD 

DSN=name , DISP=OLD 
DSN=NEWS , VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS), LABEL=(8,NL), 
DCB=( LRECL=80 , BLKSTZE=800 , RECFM=FBS ) 
DSN=WSFNS , VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(9,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=CONVERT, VOL=SER=APLDTR, 

UNIT=2400 , DISP=(OLD,PASS),LABEL=(10,NL), 
DCB=( LRECL=80 , BLKSTZE=800 , RECFM=FBS ) 
DSN=TYPEDRIL, VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(11,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=APLCOURS , VOL=SER=APLDTR, 

UNIT=2400 , DISP=( OLD, PASS ), LABEL=(12,NL), 
DCB=( LRECL=80, BLKSIZE=800 , RECFM=FBS ) 
DSN=PLOT , VOL=SER=APLDTR, 

UNIT=2400 ,DISP=( OLD, PASS), LABEL=(13,NL), 
DCB=( LRECL=80 , BLKSIZE=800, RECFM=FBS ) 
DSN=EXAMPLES , VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS), LABEL=(14,NL), 
DCB=( LRECL=80, BLKSIZE=800 , RECFM=FBS ) 
DSN=FORMAT , VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(15,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=VSFILES , VOL=SER=APLDTR, 

UNIT=2400 ,DISP=OLD, LABEL=(16,NL), 

DCB=( LRECL=80, BLKSIZE=800, RECFM=FBS ) 


SYSOUT=A 
* 
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AUTH usernum/password 

DEFINE FP NAME( APL) CODE(A0O) ENTRY( APLPCOEX ) 

DEFINE USER(1) PASSWD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000) PROJLIB( NONE) CONTENT( APL) INTPRMAX(60 30) 

DEFINE USER(2) PASSWD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000) PROJLIB( NONE) CONTENT(APL) INTPRMAX(60 30) 

DEFINE AP( 121) NOPASSWD SSMAX(30 4000000 ) 

DEFINE AP( 122) NOPASSWD SSMAX(30 4058) 

DEFINE AP( 123) NOPASSWD SSMAX( 30 32767 ) 


IMPORT 1 NEWS TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 WSFNS TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 CONVERT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 TYPEDRILL TYPE( OBJECT) CONTENT( APL) 
IMPORT 1 APLCOURSE TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 PLOT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 EXAMPLES TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 FORMAT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 2 VSFILES TYPE( OBJECT) CONTENT( APL ) 
/* 


7. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 


26 VS APL Installation Reference Material 


INSTALLING VS APL UNDER DOS/VS (VSPC) 


A description of how to install VS APL as a foreground processor under 
DOS/VS (VSPC) will be provided for subsequent releases of VS APL. 
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DEFINING VS APL USERS 


This section describes how to define VS APL users to VM/370 and VSPC. 


VM/370 User Directory 


Under CMS, a VS APL user is not defined as such. A VS APL user is a 
VM/370 user who has access to CMS and to VS APL and its libraries. The 
procedure for defining a VM/370 user directory entry is described in [BM 
Virtual Machine Facility/370: Operator’s Guide. When defining a directory 
entry for a VS APL user, observe these guidelines: 


e 


The virtual machine must be large enough to execute VS APL (see 
“Virtual Storage Requirements’’). If VS APL is installed as a shared 
system, the virtual machine size must be no larger than the load address of 
the shared system. 


The user’s CMS A-disk, in addition to whatever else he may use it for, is 
his VS APL private library. Define a disk at virtual device address 191 with 
sufficient space for anticipated workspace storage (see “Auxiliary Storage 
Requirements for Workspaces’’). 


The CMS Y-disk contains the VS APL public libraries; it can also contain 
other components of the VS APL system. Define a read-only link to this 
disk with virtual device address 19E. 


Do not define a link to a disk that contains VS APL project libraries. VS 
APL links to a project library disk dynamically as a G-disk with virtual 
device address 197. Defining a link to a project library disk could prevent 
other VS APL users from accessing project libraries. Also, do not define a 
disk with virtual device address 197 for any VS APL user. 


Define CMS as the system to be loaded when the user logs on. 
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VSPC User Profile 


Under VSPC, a VS APL user is not necessarily defined as such. A VS APL 
user is a VSPC user whose profile includes the options required for using VS 
APL. Use the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to define a new user’s profile. Use the VSPC 
ALTER command or the VSPC Service Program ALTER control statement 
to modify an existing user’s profile. They are described fully in VSPC 
Installation Reference Material. An example of DEFINE operands for a VS 
APL user is: 


Operand Description 

USER( 123456 ) Defines user number and library number 123456. 

PASSWD( MYPASS ) Defines logon password. 

LIBTYPE( PRIVATE ) User’s library is private. 

SPACE( 500 ) Maximum library space is 500 units (500,000 
bytes). 

PROJLIB( 512) User can access project library 512. 

CONTENT( APL ) When user logs on, he is under control of VS APL. 


If a CONTENT attribute other than APL is 
defined, the user can access VS APL by issuing the 
ENTER command. 


INTPRMAX( 100 50) Maximum workspace size is 100 units (100,000 
bytes). Default workspace size is 50 units (50,000 
bytes). 


SSMAX(1000 5) Maximum size of a single shared variable is 1000 
bytes. Maximum number of shared variables is 5. 


If the user intends to access VS APL workspaces in public or project libraries, 
the maximum workspace size must be at least as large as the maximum 
workspace size of those libraries. 


See also “Transferring Conversion Program Output to VSPC”’ for a 
discussion of how user profiles can be defined as a result of workspace 
conversion. 
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DEFINING AUXILIARY PROCESSORS 


This section describes how to define auxiliary processors to CMS and VSPC. 


Defining Auxiliary Processors to CMS 


Under CMS, auxiliary processors are not defined as such. An auxiliary 
processor exists as a CMS file whose filename is the name used to invoke it, 
whose filetype is TEXT, and whose filemode is any mode acceptable to CMS. 


Defining Auxiliary Processors to VSPC 


The internal auxiliary processors distributed with VS APL for use under 
VSPC are defined to VSPC during the installation procedure. They are 
identified as numbers 121 (APL VSPC file auxiliary processor), 122 
(EBCDIC VSPC file auxiliary processor), and 123 (VSAM file auxiliary 
processor). If you have obtained the source code for VS APL, you can change 
the numbers by performing these actions: 


1. Modify VS APL module APLPCOAP by specifying the new numbers as 
operands of the APAPL, APBCD, and APVSAM keywords of the 
APLPCOAP macro. Assemble the module. 


2. Link-edit the VS APL load module as described in the installation 
procedure. 


3. Execute the VSPC Service Program with DEFINE AP control statements 
to define the new numbers to VSPC (see VSPC Installation Reference 
Material). 


4. Specify the new numbers as the values of global variables APAP, APEP, 
and APVSAM in distributed workspace 2 VSFILES. 


To define a user-written auxiliary processor to VSPC, execute the VSPC 
Service Program with a DEFINE AP control statement as described in VSPC 
Installation Reference Material. 
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VS APL PUBLIC AND PROJECT LIBRARIES 


In this section, the procedures for creating and maintaining VS APL public 
and project libraries are described. 


VS APL Libraries under CMS 


Library Table File 


Under CMS, a VS APL public or project library is a collection of workspaces 
that has the properties described in the following sections. The libraries are 
defined in a CMS file called the library table file. When VS APL is installed, 
the library table file and public libraries 1 through 999 are created; no project 
libraries are created. 


The library table file defines public and project libraries to VS APL under 
CMS. The filename and filetype of the library table file are both APLIBTAB. 
The library table file distributed with VS APL defines libraries 1 through 999 
as public. When VS APL is installed, the file is placed on the Y-disk, but it 
can reside on any disk. It is located via the standard CMS search order. 


When VS APL is invoked, the library table file is read into virtual storage. 
When a VS APL user requests access to a public or project library, the 
executor searches the file sequentially from the beginning for the specified 
library number. The information from the first matching entry is used to 
identify the library type and, if a project library, to link dynamically to the 
project library disk. 


Records in the file are 80-byte card images of free format. Fields are 
delimited by one or more blanks. There are two types of records; each defines 
a single library or a range of libraries: 


PUBLIC libnum|(first-libnum last-libnum) 
PROJECT libnum|(first-libnum last-libnum) owner device 


PUBLIC or PROJECT 
is the library type; only the first two letters are required. 


libnum 
is a library number; it can be any positive integer other than 1001 
(reserved for VS APL users’ private libraries) and no greater than seven 
digits. 

(first-libnum last-libnum) 
is a range of library numbers; the first number must be less than or equal to 
the second number. 


owner 
is the VM/370 user identification of the owner of the disk on which the 
project library resides. 


device 
is the virtual device address, as defined in the owner’s directory entry, of 
the disk on which the project library resides. 


Use the CMS editor to maintain the library table file (see JBM Virtual 
Machine Facility/370: EDIT Guide). 
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Public Libraries 


How to Create a Public Library 


How to Maintain a Public Library 


For VS APL under CMS, a public library is a collection of workspaces that 
has these properties: 


e It resides on a disk that is accessed as the Y-disk. The disk can contain 
more than one public library. It must not contain project libraries. 


e It is defined as a public library in the library table file. For example, public 
libraries 1 through 999 are defined as: 


PUBLIC (1 999) 


e Each workspace in the library is a CMS file whose filetype is Wnnnnnnn, 
where nnnnnnn is the library number. For example, workspace 1 NEWS is 
a CMS file whose filename is NEWS and whose filetype is W0000001. 


« Any VS APL user can list, load, or copy workspaces in the library. 


e No VS APL user can save or drop workspaces in the library. The library is 
maintained with CMS commands. 


Public libraries 1 through 999 are defined in the distributed VS APL system. 
The disk that contains public libraries is defined during the installation 
procedure. 


To create a public library with a number greater than 999 or to change the 
distributed definition of public libraries, use the CMS editor to modify the 
library table file. 


Public library workspaces can be added, replaced, or deleted only by someone 


who is allowed write access to the public library disk. The maintenance 
functions are performed with CMS commands. The functions should be 
performed when no one is using VS APL. If this is not possible, notify VS 
APL users that they are not to access the Y-disk until the maintenance 
functions are completed. 


To add or replace a public library workspace: 


1. Have the VS APL user who created the workspace issue these CP and 
CMS commands to spool it to you: 


SPOOL PUNCH userid 
DISK DUMP filename filetype 


userid 
is your VM/370 user identification. 


filename filetype 
is the workspace identification. 


2. Access the public library disk in read/write mode and any filemode (B is 
used in the following examples). 


3. Transfer the workspace from the virtual reader to the A-disk: 


DISK LOAD 
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Project Libraries 


How to Create a Project Library 


4. Copy the workspace from the A-disk to the public library disk and rename 
it. Note that the filetype of private workspaces is VSAPLWS. For example: 


COPYFILE NEWPUB VSAPLWS A = WO0000003 B (REPLACE 


Specify the REPLACE option only if the workspace is intended to replace 
one with the same identification. 


To delete a public library workspace: 
1. Access the public library disk in read/write mode and any filemode. 
2. Erase the workspace. For example: 


ERASE NEWPUB WO000003 B 


For VS APL under CMS, a project library is a collection of workspaces that 
has these properties: 


e It resides on a disk that can be linked to dynamically as a G-disk with 
virtual device address 197. The disk can contain more than one project 
library. It must not contain public libraries. 


e It is defined as a project library in the library table file. For example, 
project library 2000 which is owned by CMS user ABC1234 and resides 
on his disk at virtual device address 196 is defined as: 


PROJECT 2000 ABC1234 196 


e Each workspace in the library is a CMS file whose filetype is Wnnnnnnn, 
where mnnnnnn is the library number. For example, workspace 2000 
PROJWORK is a CMS file whose filename is PROJWORK and whose 
filetype is W0002000. 


e Any VS APL user who knows the read password defined for the disk can 
list, load, or copy workspaces in the library. 


e Any VS APL user who knows the write password defined for the disk can 
save or drop workspaces in the library. 


To create a project library, first decide whether it is to reside on an existing 
disk or on a new disk. It must reside on a new disk if maximum access control 
is wanted. VS APL users’ access to project libraries is controlled by 
passwords associated with a disk, not with a library. 


To define the project library, use the CMS editor to add a record to the 
library table file. If the library is to reside on a new disk, define the disk as 
described in the following paragraphs; otherwise, creation of the library is 
completed. 
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The procedure for defining a disk (that is, for defining or modifying a 
VM/370 user directory entry) is described in IBM Virtual Machine 
Facility/370: Operator’s Guide. When defining a project library disk, 
observe these guidelines: 


e Define the disk in a VM/370 user directory entry that is used for no 
purpose other than to contain the definition of the project library disk(s). 
This is recommended because VS APL links to project disks dynamically 
and cannot do so if a permanent link exists. If the disk is defined in an 
active VM/370 user directory entry, that user must detach the disk each 
time he logs on. 


¢ Define passwords as required to impose the desired level of control. A VS 
APL user must specify the read password for LIB, LOAD, and COPY 
commands; the write password for SAVE and DROP commands. To allow 
uncontrolled access, define a password as ALL. 


¢ Define sufficient space for anticipated workspace storage (see “Auxiliary 
Storage Requirements for Workspaces’’). 


After the project library disk has been defined, format it using the CMS 
command FORMAT. 


How to Maintain a Project Library 


Project library workspaces can be added, replaced, or deleted by any user 
who knows the write password defined for the disk on which the project 
library resides. Maintenance is normally performed with VS APL commands 
SAVE and DROP; it can also be performed with CMS commands as 
described in ‘“How to Maintain a Public Library.” 


VS APL Libraries under VSPC 


Under VSPC, a VS APL public or project library is a VSPC public or project 
library that contains workspaces with a content attribute of APL. 


Use either the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to create a public or project library (see VSPC 
Installation Reference Material). An example of DEFINE operands for a 


public library is: 

Operand Description 

USER( 3 ) Defines user number and library number 3. 

PASSWD( XYZ ) Defines password which must be specified to 
logon as user 3 or to gain access to the library; if 
access is not to be controlled, specify 
NOPASSWD. 

LIBTYPE( PUBLIC C) Library is public; see discussion below of library 
maintenance for meaning of C. 

SPACE( 1000 ) Maximum library space is 1000 units (1,000,000 
bytes). 

CONTENT( APL ) Defines the content attribute of the workspace 
attached when a user logs on as user number 3. 

INTPRMAX( 100 50) Maximum workspace size is 100 units (100,000 
bytes); default workspace size is 50 units (50,000 
bytes). 
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The maximum workspace size must be no greater than that of VS APL users 
who access workspaces in the library. 


To define a project library, specify operands as above except for the library 
type, which is PROJECT rather than PUBLIC. 


Public and project libraries are maintained by users who have the requisite 
access to the libraries. In terms of library access, there are three types of 
users: 


e The library manager is the user who has logged on to VSPC by supplying 
the library number. 


e The workspace owner is the user who stored the workspace in the library. 


e Other users are those other than the library manager or workspace owner 
who are allowed to access the library. All users are allowed to access public 
libraries. Only those users whose profile definition includes the PROJLIB 
operand are allowed to access the specified project library. 


For both public and project libraries, if C is specified in the LIBTYPE 
operand when the library is defined, only the library manager can store, 
replace, or delete a workspace. If C is not specified, only the workspace 
owner can replace a workspace; either the workspace owner or the library 
manager can delete a workspace; other users can store new workspaces and 
thus become workspace owners. 


To store a new workspace or replace an existing one, use the VS APL 
command SAVE. To delete a workspace, use the VS APL command DROP 
or the VSPC command PURGE. 


VS APL Public and Project Libraries 37 


WORKSPACE CONVERSION 


General Information 


This section describes how to convert APL\360, APLSV, and APL/CMS 
workspaces to VS APL workspaces. Throughout this section, the term source 
APL is used to mean APL\360, APLSV, or APL/CMS. 


This section contains information that is applicable to workspace conversion 
under both CMS and VSPC unless noted otherwise. 


Pre-Conversion Considerations 


Conversion Input 


Conversion Options 


There are three items—library numbers, workspace names, and 
passwords—that may be unacceptable to CMS or VSPC. These items can be 
modified during the conversion procedure, as described later. However, they 
should be modified by the owners of the source APL workspaces before the 
workspaces are dumped. Modifying these items before rather than during the 
conversion procedure ensures that they are modified as the workspace owners 
wish them to be and simplifies the conversion procedure. 


The unacceptable items are: | 
« A library number greater than seven digits. 


« A workspace name that contains deltas, underscored letters, lowercase 
letters, or national characters. 


e« For CMS only, a workspace name longer than eight characters. 


¢ For VSPC only, a password that contains deltas or underscored characters. 
An invalid logon password can be altered by a VSPC administrator 
following conversion. An invalid workspace password must be modified by 
the workspace owner prior to conversion; a workspace with an invalid 
password cannot be accessed, and there is no way to alter the password. 


Input to the conversion procedure is a workspace dump tape from the source 
APL system. The tape can be multi-volume. For APL\360 and APLSV, the 
tape is produced by the source APL utility program; it can be a full dump, an 
incremental dump, or a selective dump. For APL/CMS, the tape is produced 
by the CMS TAPE DUMP command; it must contain only workspaces that 
were created on Version 2 of APL/CMS. 


There are three options that define which of the input workspaces are to be 
processed: 


Option Description 
Full All workspaces on the input tape are processed. 
Resume All workspaces on the input tape, beginning with a specified workspace, 


are processed. 


Select Only the specified workspaces are processed. 
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There are two options that define the type of conversion for the selected 


workspaces: 

Option Description 

Format Workspace is converted to the format defined for VS APL. 

Content Includes format conversion. In addition, all function statements are 


examined for items that will not execute correctly under VS APL. Such 
items are converted to their VS APL equivalent, if there is one. The 
incompatible items, whether converted or not, are reported. 


These types of conversion are described in greater detailin VS APL for 
CMS: Terminal User’s Guide and VS APL for VSPC: Terminal User’s 
Guide. 


Conversion Output 


Output of the conversion procedure is workspaces that can be executed by VS 
APL and a conversion report. The converted workspaces may or may not 
execute properly, depending on their content. The conversion report is 
intended for distribution to the owners of the workspaces. It gives 
information about the converted workspaces and, if content conversion was 
done, information about items that must be evaluated or modified by the 
workspace owner to ensure proper execution. 


Conversion program error messages are listed in the ‘““Messages”’ section. 


Workspace Conversion under CMS 


There are two workspace conversion programs that execute under CMS: 
APLCVCMS converts APL\360 and APLSV workspaces for use under 
CMS; APLCVRPQ converts APL/CMS workspaces for use under either 
CMS or VSPC. The procedures for using the two programs are described in 
this section and are the same unless noted otherwise. 


Auxiliary Storage Required by Conversion Programs 


When converting APL/CMS workspaces for use under VSPC, a scratch tape 
and A-disk space are required. The APLCVRPQ conversion program 
transfers each converted workspace to the tape and creates two files of job 
control statements on the converter’s A-disk. The tape and the punched JCL 
files are subsequently used with the VSPC Service Program as described in 
step 6 of the conversion procedure, below. The amount of A-disk space 
required is n 800-byte blocks, where n is the number of converted 
workspaces multiplied by 0.3. 


When converting APL/CMS workspaces for use under CMS, APL \360 
workspaces, or APLSV workspaces, only A-disk space is required. The 
APLCVRPQ and APLCVCMS conversion programs transform each input 
workspace to a CMS file on the converter’s A-disk. Estimate the amount of 
disk space required according to the number of workspaces to be converted, 
their size, and the amount of data they contain (see “Auxiliary Storage 
Requirements for Workspaces’’). If possible, use an A-disk with sufficient 
space for all the workspaces to be converted. This should be possible if the 

_ input tape is a single volume. 
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The simplest way to convert a multi-volume input tape is to segment the job 
by volume. Allocate the maximum disk space allowed by CMS (246 

cylinders) and do a separate full conversion of each volume as if it were a 
complete dump tape. Directory information, which may be present on the first 
volume of the input tape, is not needed for VS APL under CMS and is 
ignored by the conversion program. 


See the last item in step 5 of the conversion procedure for a discussion of how 
to resume conversion if it terminates abnormally because of insufficient disk 
space. 


Identification of Converted Workspaces 


When an APL \360 or APLSV workspace is converted, its identification is 
transformed to a CMS file identification. The workspace name, truncated 
from the right to eight characters, becomes the CMS filename. The library 
number, truncated from the left to seven digits or extended to the left with 
zeros to seven digits, and prefixed with a W, becomes the CMS filetype. The 
CMS filemode is always Al. For example: 


Workspace Identification CMS File Identification 

25 GENWORK GENWORK W0000025 A1 
1234567 COMPUTATION COMPUTAT W1234567 Al 
12345678 XREF XREF W2345678 A1 


When an APL/CMS workspace is converted, its identification (which is a 
CMS file identification) is retained with no change. The filetype of a private 
APL/CMS workspace is VMAPLWS. The filetype of a public APL/CMS 
workspace is Pnnnnnn, where nnnnnn is the library number. 


After workspaces have been converted, it may be necessary to change their 
identification. This can be done as part of the conversion procedure (as 
described in step 6) or by the recipients of the converted workspaces. The 
required changes are: 


e The filetype of private workspaces must be changed to VSAPLWS. 


e For APL/CMS workspaces only, the filetype of public libraries must be 
changed to Wnnnnnnn, where nnnnnnn is the library number. 


¢« For APL/CMS workspaces only, lowercase letters or national characters 
that occur in a filename must be changed to uppercase letters or numbers. 


Workspace Conversion Procedure 


1. Log on to VM/370 and IPL CMS with a virtual machine large enough to 
execute the conversion program (see “Virtual Storage Requirements’’). 


2. Access an A-disk in read/write mode with the required amount of disk 
space (see “‘Auxiliary Storage Required by Conversion Programs’’). If the 
disk is newly allocated, format it using the CMS FORMAT command. 


3. Ask the system operator to mount the workspace dump tape and to attach 
the tape drive as virtual device 181. If converting APL/CMS workspaces 
for use under VSPC, also ask the system operator to mount a scratch tape 
and to attach the tape drive as virtual device 182. 
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4. Invoke the conversion program and specify the desired options by issuing 
one of the following CMS commands: 


¢« To invoke the APL\360 and APLSV conversion program: 
APLCVCMS [FULL|RESUME|SELECT] [CONTENT |NOCONTENT] 


The meaning of the operands is described in “Conversion Options’’; 
NOCONTENT selects the format option. The operands can be 
truncated down to their initial character. The sequence in which the two 
operands are entered is immaterial. The default operands are FULL and 
CONTENT. 


¢ To invoke the APL/CMS conversion program: 
APLCVRPQ [FULL|RESUME] [CONTENT | NOCONTENT ] 


The operands are as described above. Note that the SELECT option is 
not supported. 


5. The conversion procedure is conversational. Enter information as 
explained below when prompted to do so. If the information is an APL 
workspace identification, represent APL characters with EBCDIC 
characters as follows: 


APL EBCDIC 

0-9 0-9 

A-Z a-z (lowercase) 
A-Z A-Z (uppercase) 
A * 

A $ 


Note that when the conversion program prints a workspace identification 
as part of a prompt, it uses A-Z to represent A - Z and a-z to represent 
A-Z. 


e If the input option is RESUME, enter the identification of the 
workspace at which conversion is to begin as: 


library-number workspace-name 


e If the input option is SELECT, enter a list of the workspaces to be 
converted. The list can have up to 100 entries. Each entry can be one of 
the following: . 


library-number workspace-name 
to select a specific workspace. 


library-number 
to select all workspaces in a specific library. 


Press the RETURN key after each entry. Press the RETURN key alone 
to terminate the list. Entries in the list that are not found on the input 
tape are ignored. 


¢ If converting APL/CMS workspaces, enter YES or NO (depending on 
the destination of the converted workspaces) in response to this prompt: 


IS OUTPUT FOR VSPC (YES|NO) 
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« Ifa CMS file identification duplicates that of a file already on the 
A-disk, enter one of the following options: 


Option Description 


RENAME Give the workspace a new name. In response to the 
next two prompts for filename and filetype, enter the 
desired CMS filename and filetype or press the 
RETURN key alone to leave either one unchanged. 
Filetype, if entered, must be as described earlier (W 
followed by seven digits). 


IGNORE Reject the workspace; do not convert it. 
REPLACE Replace the existing CMS file with this one. 
CANCEL Terminate execution of the conversion program. 


¢ If a workspace name is invalid (contains deltas or underscored letters), 
enter the RENAME, IGNORE, or CANCEL option as described in the 
preceding step. 


e When end of volume is reached, either enter CANCEL to terminate 
execution of the conversion program, or do the following to continue 
with the next volume: 


Enter CP mode by pressing the ATTN key twice. 


Use the CP command MSG to ask the system operator to mount the 
next volume on the tape drive attached as virtual device 181. 


— Type the CP command BEGIN. 
— Type RESTART. 


« If the conversion program terminates abnormally because the A-disk is 
full or because of an unrecoverable error, the last partially converted 
workspace is erased from the A-disk and its identification is printed at 
the terminal. Process the workspaces that have been converted by doing 
step 6 of the conversion procedure. Then rewind the input tape by 
issuing this CMS command: 


TAPE REW 


and resume the conversion procedure at step 4. Specify the RESUME 
option and the identification of the workspace that was printed when 
the conversion program terminated. 


6. When the conversion program has completed execution, process the 
converted workspaces according to their destination: 


e If the converted workspaces are to be used with VS APL under CMS 
and are not owned by the converter, separate the conversion report into 
sections by library number and distribute the sections to their owners. 
Disperse the converted workspaces to their owners and erase them from 
the A-disk by doing one of the following: 


— To change the filetype of APL\360 or APLSV private workspaces to 
VSAPLWS before dispersing them, use the CMS editor to create a 
file named NEWTYPE EXEC containing these statements: 


SCONTROL ERROR 
RENAME 6&1 &2 &3 = VSAPLWS = 
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Then issue these CP and CMS commands for each owner: 


SPOOL PUNCH userid 

LISTFILE * filetype A (EXEC 
CMS NEWTYPE 

LISTFILE * VSAPLWS A (EXEC 
CMS DISK DUMP 

CMS ERASE 


userid 
is the owner’s VM/370 user identification. 


filetype 
is that of the owner’s workspaces in the form Wnnnnnnn; it can be 
obtained from the conversion report. 


— To disperse APL\360 or APLSV workspaces without changing their 
filetype, issue these CP and CMS commands for each owner: 


SPOOL PUNCH userid 

LISTFILE * filetype A (EXEC 
CMS DISK DUMP 

CMS ERASE 


The operands are as described above. 


— To disperse APL/CMS workspaces, issue these CP and CMS 
commands for each workspace: 


SPOOL PUNCH userid 
DISK DUMP filename filetype 
ERASE filename filetype 


userid 
is the owner’s VM/370 user identification. 


filename filetype 
is the identification of the APL/CMS workspace. 


If the converted workspaces are to be used with VS APL under CMS 
and are owned by the converter, the conversion procedure is completed 
except for changing the filetype. 


To change the filetype of all private workspaces, issue this CMS 
command: 


RENAME * filetype A = VSAPLWS = 


filetype 
is either that generated for APL\360 and APLSV workspaces in the 
form Wnnnnnnn, where nnnnnnn is the source APL library number; 
or VMAPLWS for APL/CMS workspaces. 


To change the filetype of APL/CMS public workspaces, issue this CMS 
command: 


RENAME * Pnnnnnn A = Wnnnnnnn = 


nnonnnn 
is the APL/CMS library number; note that the new filetype has an 
additional zero to the left. 


¢ If the converted workspaces are APL/CMS workspaces to be used 
under VSPC, use the output of the conversion program as input to the 
IMPORT function of the VSPC Service Program. 


There are two JCL files on the A-disk. The file named IMPORT 
DDCARDS contains the DD statement shown below for each converted 
workspace. The file named IMPORT COMMANDS contains the 
IMPORT statement shown below for each converted workspace. 


//dadname DD DSN=wsname , UNIT=2400, LABEL=(n,NL), 
tf VOL=SER=XXXX , DISP=(OLD,PASS), 
res DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 


IMPORT wsname FROM(ddname) TYPE( OBJECT) CONTENT( APL) 


ddname 
is M1 through Mn, where n is the number of converted workspaces. 


wsname 
is the workspace name (the CMS filename). 


n 
is the position of the workspace on the output tape. 


The JCL files must be modified before they are used to run the VSPC 
Service Program. Use the CMS editor to modify them before printing 
and punching them, or modify them manually afterward. The required 
modifications are: 


— Add the JCL statements required by the service program. 
— Add an AUTH control statement. 


— In each DD statement, change XXXX to the serial number of the 
output tape. 


— If the output tape has standard labels, change the LABEL 
subparameter NL in each DD statement to SL. 


— If lowercase letters or national characters occur in a workspace name, 
change them to uppercase letters or numbers in the DD and IMPORT 
statements. 


— If the workspaces are to be transferred to VSPC libraries other than 
that specified in the AUTH control statement, insert the library 
number in each IMPORT statement preceding wsname. 


— If the VSPC host system is DOS/VS, use the information in file 
IMPORT DDCARDS to prepare the required TLBL statements. 


Print and punch the files by issuing these CMS commands: 


PRINT IMPORT DDCARDS 
PRINT IMPORT COMMANDS 
PUNCH IMPORT DDCARDS 
PUNCH IMPORT COMMANDS 


Send the output tape, the conversion report, and the printed and 
punched JCL files to the VSPC installation. 


At the VSPC installation, execute the VSPC Service Program to transfer 
the converted workspaces to VSPC libraries. IMPORT, AUTH, and the 
VSPC Service Program are described in VSPC Installation Reference 
Material. 
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Workspace Conversion under VSPC 


There is one workspace conversion program that executes under OS/VS 
(APLCVOS) and another that executes under DOS/VS (APLCVDOS). Both 
programs convert APL \360 and APLSV workspaces. The procedures for 
using the two programs are described in this section and are the same unless 
noted otherwise. The procedure for converting APL/CMS workspaces for use 
under VSPC is described in “‘Workspace Conversion under CMS.” 


Converting workspaces to be used under VSPC is basically a three-step 
procedure: 


1. Execute the conversion program. The output is a conversion report and a 
data set which contains the converted workspaces and user profiles. 


2. Separate the conversion report into sections by library number and 
distribute the sections to their owners. 


3. Execute the VSPC Service Program with COPY control statements to 
transfer the converted workspaces to VSPC libraries and (optionally) to 
define their owners to VSPC. Input to the VSPC Service Program is the 
data set output by the conversion program. 


If the source APL dump tape contains library numbers or workspace names 
that are unacceptable to VSPC, the procedure must be executed twice. First 
do a full conversion. The unacceptable workspaces are rejected by the 
conversion program but identified on the conversion report. Then do a 
selective conversion of the rejected workspaces using information provided by 
the workspace owners to rename them. 


Conversion Control Statements 


Input to the conversion program is an APL\360 or APLSV workspace dump 
tape and a set of control statements as described below. All control 
statements are optional. A statement can appear anywhere within columns 1 
to 71 of a card; columns 72 to 80 are ignored; continuation is not allowed. 
The operands shown in uppercase can be truncated down to their initial 
character. Operands can be separated by blanks or parentheses. If an operand 
is an APL workspace identification, represent APL characters with EBCDIC 
characters as follows: 


APL EBCDIC 

0-9 0-9 

A-Z A-Z (uppercase) 
A-Z a-z (lowercase) 
A * 

A $ 


FORMAT Statement 


Use the FORMAT statement to select format conversion. Omit the statement 
to select content conversion. The syntax of the statement, which has no 
operands, is: 


FORMAT 
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SELECT Statement 


RESUME Statement 


DESCRIBE Statement 


Use the SELECT statement to identify the libraries and/or workspaces to be 
converted during a selective conversion, and (optionally) to provide new 
identifications for workspaces with invalid library numbers or names. The 
maximum number of SELECT statements allowed is 100. If SELECT 
statements are included, RESUME is not allowed. For full conversion, omit 
both SELECT and RESUME statements. 


The syntax of the statement is: 
SELECT libnum [newlibnum] [wsname [newwsname] ] 


libnum 
is the library number of the source APL workspace. 


newlibnum 
is the VSPC library number; if omitted, the library number is 1ibnum. The 
number cannot exceed seven digits. 


wsname 
is the name of the source APL workspace; if omitted, all workspaces in the 
specified library are selected. 


newwsname 
is the name of the workspace in VSPC; if omitted, the name is wsname. 
The name cannot exceed 11 characters and cannot contain deltas or 
underscored letters. 


Use the RESUME statement to identify the workspace at which conversion is 
to resume. If RESUME is used, SELECT statements are not allowed. For full 
conversion, omit both RESUME and SELECT statements. 


The syntax of the statement is: 
RESUME libnum wsname 


libnum 
is the library number of the source APL workspace. 


wsname 
is the name of the source APL workspace. 


Use the DESCRIBE statement to supply library space and shared variable 
space values. Only one DESCRIBE statement is allowed. The values apply to 
all libraries processed by the conversion program. 


The syntax of the statement is: 
DESCRIBE [LSPACE n] [SHARE m] 


LSPACE n 
is the maximum size of a library; n is units of 1000 bytes. 


SHARE m 
is the maximum size of a shared variable; m is units of 1000 bytes. 
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The conversion program determines library space for each user as follows: 


¢ If the input tape contains directories, the LSPACE operand of the 
DESCRIBE statement is ignored. The conversion program computes 
LSPACE according to the user’s source APL workspace size (WSSIZE) 
and quota (WSQUOTA) as follows: 


X<20480[ 614441.1xWSSIZE 
Greater of 20K and source WS size plus 10% plus 6144 for internal 
buffers 


X*2048x1p0 2048T2047+X 
Rounded to nearest 2K 


VSPCSIZE+1p0 1000T999+X 
Rounded to nearest 1000 and converted to units of 1000 


LSPACE+VSPCSIZExWSQUOTA 
Multiplied by workspace quota 


e If the input tape has no directories, LSPACE is as specified in the 
DESCRIBE statement. There are no directories if the input tape is a 
selective dump, or if it is multi-volume and the first volume is not input to 
the conversion program. 


e If there is no DESCRIBE statement, or if LSPACE is not specified, 
LSPACE is 500 units. 


The conversion program specifies each user’s maximum shared variable size 
to be either that specified in the DESCRIBE statement or 0. It is the specified 
SHARE value if the input tape contains directories, the user’s directory 
indicates a shared variable quota other than 0, and a SHARE value is 
specified in the DESCRIBE statement. In all other cases, SHARE is 0. For 
APL\360, which does not support shared variables, the SHARE value 
resulting from conversion is always 0. 


Note that APLSV defines the number of shared variables that a user can 
have, but does not restrict the size of a shared variable. Therefore, if a 
SHARE value is not defined to the conversion program and not otherwise 
defined to VSPC, or if the SHARE value is inadequate, a user who migrates 
to VS APL from APLSV will not be able to execute functions that use shared 
variables. 
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OS/VS Workspace Conversion Program 


Execution of job CONVERT from the sample OS/VS JCL distributed with 
VS APL can be used to run the OS/VS conversion program. Alter the job to 
suit your requirements as noted below. 


/ /CONVERT JOB REGION=value! 

// EXEC PGM=APLCVOS 

//STEPLIB DD DSN=VSAPL.CNVTLIB, DISP=SHR 

/ /APLTLBL DD DSN=dsname, VOL=( PRIVATE, ,SER=volser), 


of UNIT=2400 , DISP=OLD, LABEL=( 1, BLP )? 
//APLTDTA DD DSN=dsname, VOL=( PRIVATE, ,SER=volser), 
// UNIT=2400 , DISP=OLD, LABEL=( 2, BLP )2 
//APLTEOV DD DSN=dsname, VOL=( PRIVATE, ,SER=volser), 
Ji UNIT=2400 , DISP=OLD, LABEL=(3,BLP )2 
//APLDIRE DD  UNIT=SYSDA,SPACE=(8004,(5,5),RLSE)3 
//APLOUT DD DSN=APLOUT, VOL=SER=volser, UNIT=2400, 
// DISP=(NEW,KEEP,KEEP ), LABEL=( ,SL)4 


//APLRPRT DD SYSOUT=A , DCB=BLKSIZE=121 
/ /SYSUDUMP DD SYSOUT=A 


//SYSIN DD #* 
Insert conversion control statementss. 
/* 


1 For region size, see “Virtual Storage Requirements.” Supply other JOB parameters according to your 


requirements. 


2 The APLTLBL, APLTDTA, and APLTEOV DD statements describe the source APL dump tape. The 
conversion program bypasses label processing. Supply the information shown in lowercase. 


The APLDIRE DD statement describes a temporary data set used by the conversion program for directory 
entries (information about each input account number). Each 8004-byte block has space for 400 entries. 
The space allocation in the sample JCL allows for conversion of 32,000 account numbers. Modify the space 
allocation, if necessary. 


4 The APLOUT DD statement describes the sequential data set created by the conversion program. It can be 
tape, as described in the sample JCL, or disk. Supply the information shown in lowercase. If output to disk 
is wanted, supply the appropriate information. 


5 Insert conversion control statements after the SYSIN DD statement. 


DOS/VS Workspace Conversion Program 


A description of the procedure for executing the DOS/VS conversion 
program will be provided for subsequent releases of VS APL. 


User Profiles Created by Conversion Program 


The data set created by the conversion program contains a user profile for 
each converted library as well as the converted workspaces. The contents of 
each user profile created by the conversion program are: 


Item Value 

USER Source APL library number or new library number specified 
in SELECT statement. 

PASSWD Source APL logon password if directories were processed by 
conversion program; otherwise NOPASSWD. 

LIBTYPE Public library if USER is less than 1000; users other than the 


library manager can store files in the library (C is not 
specified). Private library if USER is greater than or equal to 
1000. 
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Item Value 


SPACE Library space quota as determined by conversion program. 
See discussion of LSPACE in “DESCRIBE Statement.” 


CONTENT APL 

SIZE edit-size (maximum size for editable data) is 0. 
obj-size (maximum size for object programs) is 0. 

INTPRMAX maximum (maximum interpreter workspace size) is: 


X*20480fF 61444+1.1xWSSIZE 
Greater of 20K and source WS size plus 10% plus 
6144 for internal buffers 


X*X+8192 
Plus 8K 


X*2048x1900 2048T20474+X 
Rounded to nearest 2K 


MAXIMUM<1p0 10007T999+X 
Rounded to nearest 1000 and converted to units of 
1000 


default (default interpreter workspace size) is VSPCSIZE 
(see ‘DESCRIBE Statement’’). 


SSMAX size (maximum size of a shared variable) is as determined by 
conversion program. See discussion of SHARE in 
“DESCRIBE Statement.” 


number (maximum number of shared variables) is source 
APL shared variable quota if directories were processed by 
conversion program; otherwise 0. Always 0 for converted 


APL\360 workspaces. 
PROJLIB None 
JECODE None 
NOADM User not authorized to use VSPC administrator commands. 


Transferring Conversion Program Output to VSPC 


When a converted workspace is transferred to VSPC, it becomes a file in the 
VSPC library. Its library number is the source APL library number or the new 
library number specified in a SELECT statement. Its name is the source APL 
workspace name or the new workspace name specified in a SELECT 
statement. Its password is the source APL workspace password. 


Use the COPY control statement of the VSPC Service Program to transfer 
the conversion program output (converted workspaces and user profiles) to 
the VSPC library. Each user profile that does not exist in the VSPC library is 
inserted. If a user profile does exist in the library, the profile created by the 
conversion program is ignored. The converted workspaces are added to the 
newly defined or existing user libraries. 
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If the owner of converted workspaces is a new VSPC user and if the profile 
created by the conversion program is not satisfactory, either (1) use DEFINE 
to create a user profile before transferring the conversion program output; or 
(2) use ALTER to modify the user profile after transferring the conversion 
program output. 


COPY, DEFINE, ALTER, and the VSPC Service Program are described in 
VSPC Installation Reference Material. 
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TRANSPORTING WORKSPACES BETWEEN CMS 


AND VSPC 


When transporting VS APL workspaces between CMS and VSPC, no 
conversion is required. VS APL workspaces have the same format under all 
host systems. 


Transporting Workspaces from CMS to VSPC 
1. At the CMS installation: 


a. 


b. 


c. 


Ask the system operator to mount a scratch tape and to attach the tape 
drive as virtual device 181, 182, 183, or 184. 


Access the disk(s) from which the workspaces are to be transferred in 
read/only mode. 


Transfer the workspaces to tape by issuing these CMS commands for 
each workspace: 


FILEDEF DISK filename filetype filemode 
FILEDEF TAPE TAPn (RECFM F LRECL 800 BLOCK 800 
MOVEFILE DISK TAPE 


filename filetype filemode 
is the CMS identification of the workspace. 


TAPn 
is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 


d. When all workspaces have been transferred to tape, rewind and unload 


the tape: 


TAPE RUN TAPn 


2. At the VSPC installation, execute the VSPC Service Program with 
IMPORT control statements, using the tape as input, to transfer the 
workspaces to VSPC libraries. Each workspace on the tape is a separate 
data set; use one DD or TLBL statement and one IMPORT control 
statement for each. Although the input data sets contain 800-byte 
unblocked records, they must be described as 80-byte blocked records to 
the service program. For example, to transfer the third workspace on the 
tape into OS/VS (VSPC) library 512 and give it a name of THIRDWS, 
use these statements: 


//THIRDWS DD DSN=THIRDWS , VOL=SER=volser,UNIT=2400, 


// 
// 


DISP=(OLD,PASS ), LABEL=(3,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 


IMPORT 512 THIRDWS TYPE( OBJECT) CONTENT( APL ) 


See VSPC Installation Reference Material for a description of the VSPC 
Service Program and the IMPORT control statement. 
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Transporting Workspaces from VSPC to CMS 


1. At the VSPC installation, execute the VSPC Service Program with 
EXPORT control statements to transfer the workspaces to tape. Transfer 
each workspace as an unlabeled data set containing 800-byte unblocked 
records; use one DD or TLBL statement and one EXPORT control 
statement for each. For example, to transfer a workspace named 
THIRDWS from OS/VS (VSPC) library 512 as the third data set on the 
tape, use these statements: 


//THIRDWS DD DSN=THIRDWS , VOL=SER=volser , UNIT=2400, 
// DISP=( NEW, PASS ), LABEL=(3,NL), 
// DCB=( LRECL=800 , BLKSIZE=800 , RECFM=F ) 


EXPORT 512 THIRDWS 


See VSPC Installation Reference Material for a description of the VSPC 
Service Program and the EXPORT control statement. 


2. At the CMS installation: 


a. Ask the system operator to mount the tape and to attach the tape drive 
as virtual device 181, 182, 183, or 184. 


b. Access the disk(s) to which the workspaces are to be transferred in 
read/write mode. 


c. Transfer the workspaces from tape to disk by issuing these CMS 
commands for each workspace: 


FILEDEF DISK filename filetype filemode 
FILEDEF TAPE TAPn (RECFM F LRECL 800 BLOCK 800 
MOVEFILE TAPE DISK 


filename 
is the name of the workspace. 


filetype 
is VSAPLWS if the workspace is transferred to a private library; it is 
Wnnnnnnn if the workspace is transferred to a public or project 
library, where nnnnnnn is the library number. 


filemode 
is that of the disk to which the workspace is transferred. 


TAPn 
is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 
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USING THE VS APL MICROCODE ASSIST 


The VS APL microcode assist, which is available for System/370 Models 135 
and 145, performs some of the functions of the VS APL interpreter. The 
procedure for loading the microcode assist is described in Operator’s Library: 
System/370 Model 135 Procedures and IBM System/370 Model 145 


Operator Procedures. If the microcode assist is there when VS APL is 
invoked, it is detected and used. 
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STORAGE REQUIREMENTS 


Virtual Storage Requirements 


Figure 2 shows the minimum virtual machine size (VM/370) and region size 
(OS/VS) required to install and execute VS APL and to execute the 
workspace conversion programs. Virtual storage requirements for VS APL 
under DOS/VS (VSPC) will be provided for subsequent releases of VS APL. 


Host To Install To Execute To Execute 
System VS APL VS APL Conversion Program 
VM/370 (CMS) 400K 400K! 200K + 3.1 x WS5 for APLCVCMS 
(APL non-shared) 
200K + 2.1 x WS® for APLCVRPQ 
VM/370 (CMS) SSA2 + 400K 320K3 as above 
(APL shared) 
OS/VS (VSPC) 256K 175K4 124K + 3.1 x WSS 


1 Assumes a minimum-size workspace (20K) and no auxiliary processors. To execute with all distributed 
auxiliary processors and 4K of shared memory, add 20K. For additional shared memory or larger 
workspace, increase virtual machine size correspondingly. Users who access a large number of disks and 
files may require additional storage for CMS control blocks. 


2 Where SSA is the shared system’s load address. 


3 This is the minimum-size CMS virtual machine. It allows a 100K workspace. You can increase the size of 
the virtual machine as noted in 1 above, but must not exceed the load address of the shared system. In 
addition, 192K (3 segments) of shared main storage is required. 


4 This is the virtual storage required for the VS APL interpreter and executor (including the internal 
auxiliary processors), rather than the region size. It does not include virtual storage required for VSPC, 
access methods, and workspaces. 


5 Where WS is the size of each source APL workspace. 


6 Where WS is the size of the largest source APL workspace; virtual machine size must be at least 264K. 


Figure 2. Virtual Storage Requirements for VS APL 


Auxiliary Storage Requirements 
In this section, direct access storage devices are identified as follows: 
2314: IBM 2314 Direct Access Storage Facility and IBM 2319 Disk Storage. 
3330: IBM 3330 Disk Storage and IBM 3333 Disk Storage and Control. 
3340: IBM 3340 Direct Access Storage Facility. 


Auxiliary Storage Requirements for VS APL 


Figure 3 shows the minimum auxiliary storage required to install VS APL 

as a non-shared system under CMS. Note the columns that indicate whether 
the storage requirement applies to the A-disk, the Y-disk, or both. The total 
cylinder requirements for each disk are computed using the total block 
requirements; they are not the sum of the cylinders required for each 
component. 


Figure 4 shows a summary of the minimum auxiliary storage required to 
install VS APL as a shared system under CMS. The detail is as shown in 
Figure 3, except that component APL MODULE requires 8 blocks and there 
is an additional component, APLMAIN MODULE, that requires 232 blocks 
on the A-disk. 
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Disk  800-byte Cylinders 


Component A YY Blocks 2314 3330 3340 
TEXT files for executor, x 620 5 3 7 
interpreter, shared storage 

manager 

TEXT files for conversion x 220 2 1 3 
programs 

Link-edit maps x 120 1 1 2 
Macros x 100 1 1 2 
APLINSTL EXEC X 50 1 1 1 
APL MODULE x xX 240 2 1 3 
APLCVCMS MODULE x X 75 1 1 1 
APLCVRPQ MODULE x xX 75 1 1 1 
APL EXEC x X 2 1 1 1 
APLCVCMS EXEC x X 2 1 1 1 
APLCVRPQ EXEC x X 2 1 1 1 
Auxiliary processors x xX 40 1 1 1 
APLMAC MACLIB x xX 95 1 1 1 
Library table file x xX 1 1 1 
Distributed workspaces x 300 2 2 4 
Total for A-disk x 1642 11 7 18 
Total for Y-disk X 832 6 4 9 


Figure 3. Auxiliary Storage Requirements for Non-Shared VS APL under CMS 


Cylinders 
Storage Device Unit of Storage Units Required 2314 3330 3340 
A-disk 800-byte block 1642 11 7 18 
Y-disk 800-byte block 600 4 3 7 
CP volume 4K page 49 2 1 3 


Figure 4. Auxiliary Storage Requirements for Shared VS APL under CMS 


Figure 5 shows the minimum auxiliary storage required to install VS APL 
under OS/VS (VSPC). The VSPC library storage requirement is for the 
distributed workspaces. 


The amount of auxiliary storage required to install VS APL under DOS/VS 
(VSPC) will be provided for subsequent releases of VS APL. 


Auxiliary Storage Requirements for Workspaces 


The amount of auxiliary storage required for a workspace depends on the 
amount of data it contains, not on the size of the workspace. To compute the 
number of bytes required to store a workspace, subtract the space available, 
OWA, from the workspace size, )WSSIZE. 


Under VSPC, a VS APL workspace is a VSPC file. VSPC files are stored in 
units of 1000 bytes. 


Under CMS, a VS APL workspace is a CMS file with a block size of 800 
bytes. Figure 6 shows the capacity per cylinder of the direct access storage 
devices supported by CMS in terms of 800-byte blocks and several data sizes. 
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Data Set Data Set Type 
SYS1.LINKLIB partitioned 
(OS/VS1 only) 

SYS1.LPALIB partitioned 
(OS/VS2 only) 

VSAPL.OBJLIB partitioned 
VSAPL.CNVTLIB _spartitioned 
VSPC library VSAM 


Number of 
Directory 
Blocks 


1 


20 


Unit of 
Storage 


cylinder! 


cylinder! 


3520-byte 
block 


cylinder! 


1000-byte 
unit 


1 Storage requirements for load module data sets are for a 3330. 


Figure 5. 

15K 
Device Blocks ClearWS Data 
2314 150 25 7.5 
3330 266 44.3 13.3 
3340 96 16 4.8 


Figure 6. Auxiliary Storage Capacity per Cylinder 


25K 
Data 


4.5 
8.1 
2.9 


50K 
Data 


2.3 
4.1 
1.5 


Auxiliary Storage Requirements for VS APL under OS/VS (VSPC) 
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MESSAGES 


Messages under CMS 


Messages under VSPC 


Error and diagnostic messages that are issued by the CMS executor of VS 
APL are printed at the user’s terminal. They are identified by a message 
number prefix of APL. They are documented in VS APL for CMS: 
Terminal User’s Guide. 


A VS APL user can also receive messages issued by CP or CMS. CP and 
CMS messages are identified by message number prefixes of DMK and DMS, 
respectively. They are documented in IBM Virtual Machine Facility/370: 
System Messages. 


The following error and diagnostic messages are issued by the VSPC executor 
of VS APL and are printed on the VSPC online log. The VS APL user 
receives the message SYSTEM ERROR nnn, where nnn is the online log 
message number. 


APLP001I PGM CHECK LOOP IN APL PROCESSOR. 


Explanation: During processing of a program check, a second program check 
occurred. 


System Action: Message APLPO11I, which shows the PSW and general 
registers at the time of the second program check, is issued. A dump is taken, 
and execution is terminated. 


User Action: Report the problem to the system programmer. 


APLP002I PGM CHECK IN EXECUTOR. 


Explanation: A program check occurred in the VS APL executor. 


System Action: Message APLPOQ11I, which shows the PSW and general 
registers at the time of the program check, is issued. A dump is taken, and 
execution is terminated. 


User Action: Report the problem to the system programmer. 


APLP003I EXECUTOR SAVE AREA BLOCK FULL. 


Explanation: The executor is designed so that routine calls are nested to a 
maximum depth of five. An attempt to call a sixth-level routine was made, 
and there is no sixth save area. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the system programmer. 


APLP004I INVALID ASSIST CHECK CONDITION CODE. 


Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, an unexpected condition code was returned. 


System Action: Execution continues without use of the VS APL microcode 
assist. 


User Action: Report the problem to the system programmer. 
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APLPO0OSI UNEXPECTED SYSTEM ERROR CODE RECEIVED. 
RET: xxx, REAS: yyy, SYS: www, APL: 2zzzz. 


Explanation: An unexpected error code was received from VSPC following a 
service request. xxx is the return code, yyy is the reason code, www is the 
VSPC request code, zzzzz is the VS APL service request code. 


System Action: A dump is taken. A clear workspace is loaded. Execution 
continues. 


User Action: Report the problem to the system programmer. 


APLP006I NO SYSTEM INDICATOR ON ASYNCH ENTRY. 


Explanation: VSPC invoked the VS APL processor for an asynchronous 
occurrence. No indicator was set to distinguish the cause. 


System Action: A dump is taken. Execution continues. 


User Action: Report the problem to the system programmer. 


APLP007I_ MULTIPLE UNEXPECTED ERROR CODES FROM 
SYSTEM. 


Explanation: Multiple unexpected error codes were received from VSPC 
following similar service requests. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the system programmer. 


APLP0O8I APL ASSIST INCOMPATIBLE WITH APL PROCESSOR. 


Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, it was discovered that the microcode assist is 
not at the same level as the VS APL processor. 


System Action: Execution continues without use of the VS APL microcode 
assist. 


User Action: Report the problem to the system programmer. 


APLP009I INSUFFICIENT STORAGE FOR MINIMUM WS. 


Explanation: The minimum workspace size defined in the user’s profile is too 
small for VS APL operation. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the account administrator. 


APLPO1 11) PSW: xxxxxxxx xxxxxxxx, REGS: 


Explanation : VS APL has been terminated because of a program check. This 
message shows the contents of the program check old PSW and the general 
registers. It is issued following messages APLPOO1I or APLPOOZ2I. 


System Action: Abend processing continues. 


User Action: Include this information when reporting the problem to the 
system programmer. 
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APLP014I_ UNEXPECTED ERROR IN APL INTERNAL AP. 


Explanation: An unexpected error code was received from VSPC following a 
service request in an internal auxiliary processor. The prior message, 
APLPOOSI, gives additional information about the error. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the system programmer. 


Conversion Program Messages 


The following error messages are issued by workspace conversion programs 
and appear on the conversion report. With the conversion programs that run 
under CMS, the messages are also printed at the terminal. When a workspace 
or library is in error, its identification either appears in the message or 
preceding the message in the conversion report. 


There are messages in addition to those listed below that appear on the 
conversion report. They are directed to the workspace owner and are 
documented in VS APL for CMS: Terminal User’s Guide and VS APL 
for VSPC: Terminal User’s Guide. 

*** HDR LABEL I/O ERROR. CONVERSION CANCELLED 


Explanation: An unrecoverable error occurred while an input header label 
was being read. 


System Action: Execution of the conversion program is terminated. 


User Action: Obtain another copy of the input tape from the source APL 
system. 


Issued by: APLCVCMS, APLCVOS, APLCVDOS. 


*** TRLR LABEL I/O ERROR. CONVERSION CANCELLED 


Explanation: An unrecoverable error occurred while an input trailer label was 
being read. 


System Action: Execution of the conversion program is terminated. 


User Action: If the error occurred on the last or only volume, none. 
Otherwise, run the conversion program again using the remaining volumes. 


Issued by: APLCVCMS, APLCVOS, APLCVDOS. 
SYSTEM ERROR WHILE CONVERTING WORKSPACE/DIRECTORY 


libnum name. WORKSPACE/DIRECTORY UNCONVERTED AND 
PRESUMED DAMAGED 


Explanation: A program check occurred, probably because of invalid 
information in a workspace or directory. 


System Action: The contents of the program check old PSW and general 
registers are printed. Execution of the conversion program continues with the 
next workspace. 


User Action: Obtain another copy of the rejected workspace or library from 
the source APL system. 


Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 
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ERROR UNRECOVERABLE. CONVERSION ABORTED 
Explanation: Repeated system errors have occurred. 


System Action: A storage dump is printed. Execution of the conversion 
program is terminated. 


User Action: Obtain another copy of the input tape from the source APL 
system. 


Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 
*** WORKSPACE REJECTED, NOT CONVERTED, DUE TO I/O ERROR 


Explanation: An unrecoverable error occurred while the workspace was being 
read. 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Obtain another copy of the rejected workspace from the source 
APL system. 


Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 


WORKSPACE FULL 
Explanation: The workspace is too large to be converted. 


System Action: Execution of the conversion program continues with the next 
object in the workspace. 


User Action: Have the owner of the source workspace compress it or split it 
into two workspaces and obtain a dump of the modified workspace. 


Issued by: APLCVCMS, APLCVOS, APLCVDOS. 
WRITE ERROR nn WHILE SAVING libnum name. CONVERSION 
CANCELLED 


Explanation: An error return from the FSWRITE macro occurred. nn is the 
return code (see IBM Virtual Machine Facility/370: Command Language 
Guide for General Users.) The probable cause of the error is a full A-disk 
(return code 13). 


System Action: Execution of the conversion program is terminated. 


User Action: Determine the reason for the error and correct it. Then run the 
conversion program again, specifying the RESUME option and the 
identification of the rejected workspace. 


Issued by: APLCVCMS. 


filename filetype TAPORT FILE SEQUENCE NUMBER nnnn 


Explanation: Display of the file sequence number nnnn of the converted 
workspace filename filetype on the output tape. 


System Action: None. 


User Action: Use the information when preparing VSPC Service Program 
control statements. 


Issued by: APLCVRPQ. 
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NOT A CMS DUMP TAPE. CONVERSION CANCELLED 
Explanation: The input tape is not a CMS dump tape. 

System Action: Execution of the conversion program is terminated. 
User Action: Mount the correct tape. 


Issued by: APLCVRPQ. 


filename filetype filemode NOT AN APL/CMS (PRPQ) WORKSPACE. 
Explanation: The file is not an APL/CMS workspace. 


System Action: Execution of the conversion program continues with the next 
file. 


User Action: None, unless all files on the tape are so rejected. In this case, 
mount the correct tape. 


Issued by: APLCVRPQ. 

INADEQUATE SPACE TO RUN CONVERSION. CONVERSION 
CANCELLED 

Explanation: There is less than 64K of free virtual storage space available. 
System Action: Execution of the conversion program is terminated. 

User Action: Define a larger virtual machine. 

Issued by: APLCVRPQ. 

filename filetype WORKSPACE TOO LARGE FOR VIRTUAL MACHINE 


SIZE. RERUN WITH LARGER MACHINE. WSSIZE IS xxxx NEED 
ABOUT yyyy BYTES TO CONVERT. 


Explanation: The workspace is too large to be converted. 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Define a larger virtual machine and run the conversion program 
again. 


Issued by: APLCVRPQ. 
filename filetype WORKSPACE DAMAGED OR INVALID. NOT 
CONVERTED. 


Explanation: Either internal pointers in the workspace are invalid, or the 
workspace is not Version 2. 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Obtain a valid copy of the rejected workspace from the source 
APL system. 


Issued by: APLCVRPQ. 


Messages 65 


*** WSID INVALID FOR VSPC. WORKSPACE (OR LIBRARY) 
REJECTED 


Explanation: The workspace name contains deltas or underscored characters 
or the library number exceeds seven digits. 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Run the conversion program again, using a SELECT statement 
to provide a valid identification for the rejected workspace or library. 


Issued by: APLCVOS, APLCVDOS. 
* THIS LIBRARY DEFINED WITH DEFAULTS DUE TO SYSTEM 
ERROR 


Explanation: An error occurred while the directory for the library was being 
read. 


System Action: A user profile record containing default values for SPACE 
and SSMAX< is written (see “User Profiles Created by Conversion Program’’). 
Execution of the conversion program continues. 


User Action: If defaults are acceptable, none. Otherwise, use the VSPC 
command ALTER to modify the user’s profile. 


Issued by: APLCVOS, APLCVDOS. 


SELECTION LIST FULL. COMMAND IGNORED 


Explanation: More than 100 SELECT statements were input to the 
conversion program. 


System Action: The SELECT statements in excess of 100 are ignored. 


User Action: Run the conversion program with the rejected SELECT 
statements. 


Issued by: APLCVOS, APLCVDOS. 


INVALID SELECT PARAMETER. COMMAND IGNORED 
Explanation: The SELECT statement contains an invalid parameter. 
System Action: The invalid statement is ignored. 


User Action: Correct the SELECT statement and run the conversion 
program again. 


Issued by: APLCVOS, APLCVDOS. 


INVALID DESCRIBE COMMAND. CONVERSION CANCELLED 
Explanation: The DESCRIBE statement contains an invalid parameter. 
System Action: Execution of the conversion program is terminated. 


User Action: Correct the DESCRIBE statement and run the conversion 
program again. 


Issued by: APLCVOS, APLCVDOS. 
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INVALID CONVERSION OPTIONS. CONVERSION CANCELLED 


Explanation: Either the RESUME statement contains an invalid parameter or 
a conversion control statement is unrecognizable. 


System Action: Execution of the conversion program is terminated. 


User Action: Correct the invalid statement and run the conversion program 
again. 


Issued by: APLCVOS, APLCVDOS. 
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APPENDIX A. VS APL COMPONENTS 


Listed below are the items that 
are contained in each component 
of VS APL. When you install VS 
APL, check the printed output of 
the installation procedure against 
these lists to verify that each 
component is complete. 


Interpreter Modules 


APLCOIBM 
APLIACHK 
APLIACIR 
APLIADEC 
APLIADOM 
APLIAENC 
APLIAFOR 
APLIAGFM 
APLIAGOU 
APLIAGRD 
APLIANAM 
APLIAPRD 
APLIAQFN 
APLIARED 
APLIAROT 
APLIASCN 
APLIASHF 
APLIASHV 
APLIASYV 
APLIATAK 
APLIATBC 
APLIATRN 
APLIATRS 
APLIATSP 
APLIECMX 
APLIEFCH 
APLIEFNM 
APLIEIDX 
APLIEMND 
APLIEPSI 
APLIEREV 
APLIERHO 
APLIESCA 
APLIESPA 
APLIETAK 
APLIEXAR 
APLIEXFR 
APLITCMC 
APLITCMD 
APLITCME 
APLITCMF 
APLITCMG 
APLITCMI 


APLITCML 
APLITCMS 
APLITCMT 
APLITCPI 
APLITCPO 
APLITERR 
APLITEX 
APLITFCH 
APLITFDC 
APLITFDE 
APLITFDN 
APLITFDO 
APLITFUN 
APLITHDR 
APLITIDS 
APLITIHI 
APLITINI 
APLITINP 
APLITLXS 
APLITMSG 
APLITNCV 
APLITPRL 
APLITSUB 
APLITUSG 


CMS Executor Modules 


APLSCDPY 
APLSCERR 
APLSCFXI 
APLSCINI 
APLSCLIB 
APLSCMSC 
APLSCMSG 
APLSCOPY 
APLSCSHV 
APLSCSVI 
APLSCTBL 
APLSCTYP 


VSPC Executor Modules 


APLPAPAB 
APLPAPCD 
APLPCOAP 
APLPCOEX 
APLPCTBL 
APLPFXIM 
APLPLIBS 
APLPMISC 
APLPSERR 
APLPSHVR 
APLPTYIO 


Shared Storage Manager Modules 


(CMS only) 


ASUSHACC 
ASUSHBPB 
ASUSHBVB 
ASUSHCPY 
ASUSHGET 
ASUSHOFR 
ASUSHPUT 
ASUSHQUE 
ASUSHREF 
ASUSHRET 
ASUSHSOF 
ASUSHSON 
ASUSHSPC 
ASUSHSRD 
ASUSHSUB 


Auxiliary Processors (CMS only) 


APL100 
APL101 
APL110 
APL111 


Auxiliary Processor Macros 


(CMS only) 


APLZCODE 
ASUPCV 
ASUSCV 
ASUSHSVP 
ASVPACC 
ASVPCPY 
ASVPOFR 
ASVPQRY 
ASVPREF 
ASVPRET 
ASVPSOF 
ASVPSON 
ASVPSPC 
ASVPWAIT 


CMS Conversion Modules (for 
APLCVCMS) 


APLCCULL 
APLCDISP 

APLCFUNC 
APLCGRUP 
APLCIBNM 
APLCINIT 

APLCLEAR 
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APLCMISC 
APLCOIBM 
APLCPARM 
APLCRPRT 
APLCSAVE 
APLCSHIP 
APLCSPIE 
APLCTBCD 
APLCVARB 
APLCWKSP 
APLCWSFN 
APLIESPA 
APLIEREV 
APLITFDC 
APLITHDR 
APLITIDS 
APLITLXS 
APLITNCV 


CMS Conversion Modules (for 
APLCVRPQ) 


APLCOIBM 
APLCSHIP 
APLCSPIE 
APLCTBCD 
APLIESPA 
APLITFDC 
APLITHDR 
APLITIDS 
APLITLXS 
APLITNCV 
APLQDISP 
APLQFUNC 
APLQGRUP 
APLQIBNM 
APLQINIT 
APLQLEAR 
APLQMISC 
APLQPARM 
APLQRPRT 
APLQSAVE 
APLOQVARB 
APLQWKSP 


VSPC/OS Conversion Modules 


APLCOIBM 
APLIESPA 
APLIEREV 
APLITFDC 
APLITHDR 
APLITIDS 
APLITLXS 
APLITNCV 
APLOCULL 
APLODIRE 
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APLODISP 
APLOFUNC 
APLOGRUP 
APLOIBNM 
APLOINIT 
APLOLEAR 
APLOMISC 
APLOPARM 
APLORPRT 
APLOSAVE 
APLOSHIP 
APLOSLST 
APLOSPIE 
APLOTBCD 
APLOTIDY 
APLOVARB 
APLOWKSP 
APLOWSFN 


APPENDIX B. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER CMS 


Log on to VM/370, IPL CMS, and execute the VS APL session shown 
below. You must have access to the disk on which the VS APL system resides 
and to the Y-disk on which the distributed workspaces reside. 


APL APL100 Invoke VS APL and the 
auxiliary processor that 
issues CP and CMS commands 


VS APL 
CLEAR WS 

100 OSVO 'x! Establish connection with 
2 auxiliary processor 

X«'Z * WO000001 Y'! Issue CMS command to list 
NEWS WOO0O00001 Y1 workspaces in public library 1 


TYPEDRIL W0000001 Y1 
APLCOURS WO000001 Y1 
CONVERT WO0000001 Yi 
EXAMPLES W0000001 /Y1 


PLOT WO000001 /Y1 
FORMAT WOO0O0O0O001 Y1 
WSFNS WO000001 Yi 

)LOAD 1 EXAMPLES Load workspace 
SAVED 08:50:42 06/12/75 

FINDTYPE '‘'7' Data type of argument is ... 
1 character 

FINDTYPE 7 Data type of argument is ... 
0 numeric 

)OFF HOLD Log off VS APL and return 
el to CMS 
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APPENDIX C. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER VSPC 


Log on to VSPC and execute the VS APL session shown below. If the user 
number that you log on with has a content attribute of APL, omit the first 


statement. 

ENTER APL Invoke VS APL 
VS APL 

CLEAR WS 
)LOAD 2 VSFILES Load workspace 


SAVED 11:05:17 07/29/75 
'S' ACREATE 'SAMPLE' Create VSPC APL file to 
be accessed sequentially 


AWRITE 3 4p112 Open file and write record 1 
AWRITE 4 39112 Write record 2 
AREAD Read record 1 
i 2 3 4 
5 6 7 8 
9 10 11 12 
AREAD Read record 2 
1 2 3 
4 5 6 
7 8 9 
40-11. 12 
AREAD There is no record 3; 
file is closed 
DROP '‘SAMPLE' Purge the file 
)OFF HOLD Log off VS APL and return 
peaLlt to VSPC 
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GLOSSARY 


The following terms are defined as they are used in this 
publication. If you do not find the term you are looking for, 
refer to the index or to the IBM Data Processing Glossary, 
GC20-1699. 


A-disk: In CMS, a user’s primary disk; accessed in read/write 
mode when a CMS terminal session is begun. 


account administrator: A VSPC user who has limited authority 
to use the VSPC Service Program and to define and alter user 
profiles. 


auxiliary processor: A program that communicates with other 
programs via shared variables. 


chief administrator: A VSPC user who has full authority to use 
the VSPC Service Program and to define and alter user, 
foreground processor, and auxiliary processor profiles. 


content attribute: In VSPC, information associated with a 
workspace that identifies its foreground processor or 
indicates its contents. 


content conversion: A form of workspace conversion in which 
the contents of a workspace are analyzed and modified; 
includes format conversion. 


conversion program: The component of VS APL that converts 
APL \360, APLSV, and APL/CMS workspaces to VS APL 
workspaces. 


executor: The component of VS APL that provides 
environment-dependent services for the interpreter. 


filemode: In CMS, the third field of a file identifier; identifies 
the virtual disk on which the file resides and the mode in 
which the disk can be accessed. 


filename: In CMS, the first field of a file identifier. 


filetype: In CMS, the second field of a file identifier; may 
implicitly define certain file characteristics. 


foreground processor: A processor, such as VS APL, that 
operates under the control of VSPC. 


format conversion: A form of workspace conversion in which 
only the format of a workspace is modified. 


full conversion: A form of workspace conversion in which all 
input workspaces are converted. 


internal auxiliary processor: An auxiliary processor that is part 
of the VS APL (VSPC) executor, rather than a separate 
program. 


interpreter: The component of VS APL that scans, analyzes, 
and executes VS APL statements. 


library manager: A VSPC user whose user number is that of a 
public or project library. 


library table file: A file that defines public and project 
libraries to VS APL under CMS. 


private library: A library that is normally available only to a 
single user. 


profile: A collection of information about a user, a 
foreground processor, or an auxiliary processor. 


project library: A library that is normally available to a set of 
users. 


public library: A library that is normally available to all users. 


selective conversion: A form of workspace conversion in 
which only specified input workspaces are converted. 


service program: In VSPC, a program that is used to manage 
the VSPC library and to define and alter profiles. 


shared storage manager: The component of VSPC or of VS 
APL under CMS that manages the communication between 
auxiliary processors. 


system disk: In CMS, the disk that contains the CMS nucleus 
and disk-resident command modules; accessed in read/only 
mode when a CMS terminal session is begun. 


workspace: An area of virtual storage assigned to a user for 
his exclusive use. Also, the contents of that area when stored 
as a file. 


Y-disk: In CMS, a disk that is an extension of the system disk. 
It contains VS APL modules, procedures, and public libraries. 


Glossary 75 


INDEX 


A 


A-disk, CMS 
for installing VS APL 16-17 
for VS APL user 29 
for workspace conversion 40 
list of files 17 
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under CMS 43 
under VSPC 47 
required changes 39,41,45 
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description 11 
list of contents 69-70’ 
content conversion 
description 40 
how to specify 
for CMS 42 
for VSPC 46 
conversion (see workspace conversion ) 
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under CMS 33-36 
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DEFINE statement, VSPC 
for auxiliary processors 26 
for converted libraries 49-50 
for project libraries 37 
for public libraries 36,26 
for VS APL 26 
for VS APL user 30 
defining auxiliary processors 
to CMS 31 
to VSPC 31,25-26 


defining VS APL libraries 
to CMS 33-36 
to VSPC 36-37,25-26 
defining VS APL users 
to VM/370 29 
to VSPC 30 
DESCRIBE statement, conversion 
program 47-48 
directory entry, VM/370 
for project library disk 36 
for VS APL user 29 
distributed workspaces 
auxiliary storage 
requirements 57-59 
description 11 
how to transfer to VSPC 25-26 
identification 13 
distribution volume, VS APL 13 
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error messages 
conversion program 63-67 
under CMS 61 
under VSPC 61-63 
executor, VS APL 
description 11 
list of modules 69 
messages 61-63 
EXPORT statement, VSPC 54 
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format conversion 
description 40 
how to specify 
for CMS 42 
for VSPC 46 
format of conversion program 
statements 46 
format of VS APL distribution 
volume 13 
FORMAT statement, conversion 
program 46 
full conversion 
description 39 
how to specify 
for CMS 42 
for VSPC 47 
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G-disk, CMS 
for project libraries 35 
how to define 36 
restriction on definition 29,36 
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how to maintain a public 
library 3435 
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IMPORT statement, VSPC 
for converted workspaces 45 
for distributed workspaces 26 
for workspaces transported from 
CMS 53 
installing VS APL 
under DOS/VS (VSPC) 27 
under OS/VS (VSPC) 21-26 
under VM/370 (CMS) 15-19 
internal auxiliary processors 
description 11 
how to define to VSPC 25-26 
identification 31 
interpreter, VS APL 
description 11 
list of modules 69 
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JCL for OS/VS 

how to punch 22 

to build VS APL object module 
library 23 

to define OS libraries 23 

to link-edit conversion program 24 

to link-edit VS APL load 
module 24 

to run conversion program 49 

to run VSPC Service 
Program 25-26 
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library (see private library, project 
library, public library) 

library number, restriction 39 
library space quota 48 
library table file 33 
link-edit 

conversion program 24 

VS APL load module 24 
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macros, auxiliary processor 
description 11 
list of names 69 
maintaining VS APL libraries 
under CMS 34-36 
under VSPC 37 
messages 
conversion program 63-67 
under CMS 61 
under VSPC 61-63 
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OS/VS workspace conversion 
program 49 
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passwords 
for project library disks 36 
for VSPC, restrictions 39 
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under CMS 29 
under VSPC 30 
profile, VSPC user 
created by conversion 
program 49-50 
example 30 
project library 
under CMS 
description 35 
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how to maintain 36 
under VSPC 
how to create 37 
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public library 
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description 34 
how to add or replace a 
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how to create 34 
how to delete a workspace 35 
under VSPC 
how to create 36 
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quotas, VSPC 
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number of shared variables 50 
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RESUME statement, conversion 
program 47 
resuming workspace conversion 
description 39 
under CMS 42-43 
under VSPC 47 
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sample JCL (see JCL) 
sample terminal session 
for CMS 71 
for VSPC 73 
selective conversion 
description 39 
how to specify 
forCMS 42 
for VSPC 47 
SELECT statement, conversion 
program 47 
shared storage manager 
description 11 
list of modules 69 
shared variable quotas 48,50 
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installing 15-19 
storage requirements 
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storage requirements 
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for workspace conversion 40 
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virtual storage 57 
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terminal session, sample 
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example 30 
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input 
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output 
general description 40 
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procedure 41-45 
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